smartcomply-web-sdk 1.0.43 → 1.0.47

package/dist/flow/SmartComplyFlow.js

@@ -10,22 +10,25 @@ const STEP_ORDER = [
     "welcome",
     "country",
     "id_type",
-    "id_input", // or document_capture
+    "id_input",
+    "confirm_identity",
     "document_capture",
-    "processing",
+    "ocr_gate",
+    "document_confirm",
     "liveness",
+    "done",
     "result",
 ];
 const COUNTRY_LABELS = {
-    nigeria: "🇳🇬  Nigeria",
-    global: "🌍  Other Countries",
-    ghana: "🇬🇭  Ghana",
-    kenya: "🇰🇪  Kenya",
-    south_africa: "🇿🇦  South Africa",
-    united_states: "🇺🇸  United States",
-    united_kingdom: "🇬🇧  United Kingdom",
+    nigeria: "🇳🇬  Nigeria",
+    global: "🌍  Other Countries",
+    ghana: "🇬🇭  Ghana",
+    kenya: "🇰🇪  Kenya",
+    south_africa: "🇿🇦  South Africa",
+    united_states: "🇺🇸  United States",
+    united_kingdom: "🇬🇧  United Kingdom",
 };
-// Backend/admin data tags document-capture fields inconsistently — the field
+// Backend/admin data tags document-capture fields inconsistently — the field
 // renderer (below) already treats "image" and "file" as file inputs alongside
 // "upload", so flow-routing decisions must recognize the same set or a channel
 // tagged "image"/"file" silently falls back to the number-entry screen.
@@ -35,7 +38,7 @@ function isUploadFieldType(type) {
 function resolveIdTypeInfo(typeName, isDocumentFlow) {
     const u = typeName.toUpperCase();
     const advanced = u.includes("ADVANCED");
-    // Strip UI noise from display labels — users don't need "with face" or "(NIN)" suffixes
+    // Strip UI noise from display labels — users don't need "with face" or "(NIN)" suffixes
     const cleanName = typeName
         .replace(/\s*with\s+face\s*/gi, ' ')
         .replace(/\s*\(NIN\)\s*/gi, ' ')
@@ -50,41 +53,41 @@ function resolveIdTypeInfo(typeName, isDocumentFlow) {
             t.includes("license") ||
             t.includes("national id") ||
             t.includes("national id card");
-        // Note: NIN document (nin_with_face, nin_slip) does NOT require back side —
+        // Note: NIN document (nin_with_face, nin_slip) does NOT require back side —
         // the NIN card is single-sided. Only the physical NIN slip has a back but
         // the OCR pipeline only needs the front.
     };
-    // BVN — always 11 digits
+    // BVN — always 11 digits
     if (u.includes("BVN") || u.includes("BANK VERIFICATION")) {
-        return { icon: "🏦", desc: "Enter your 11-digit Bank Verification Number (BVN)", requiresBack: false };
+        return { icon: "🏦", desc: "Enter your 11-digit Bank Verification Number (BVN)", requiresBack: false };
     }
-    // NIN — always 11 digits (covers nin_with_face, NIN slip, etc.)
+    // NIN — always 11 digits (covers nin_with_face, NIN slip, etc.)
     if (u.includes("NIN") || u.includes("NATIONAL IDENTITY NUMBER")) {
-        return { icon: "🆔", desc: "Enter your 11-digit National Identification Number (NIN)", requiresBack: false };
+        return { icon: "🆔", desc: "Enter your 11-digit National Identification Number (NIN)", requiresBack: false };
     }
     // Ghana Card / Ghana National ID
     if (u.includes("GHANA")) {
         if (isDocumentFlow)
-            return { icon: "🪪", desc: "Capture or upload your Ghana Card", requiresBack: true };
-        return { icon: "🪪", desc: "Enter your Ghana Card number", requiresBack: false };
+            return { icon: "🪪", desc: "Capture or upload your Ghana Card", requiresBack: true };
+        return { icon: "🪪", desc: "Enter your Ghana Card number", requiresBack: false };
     }
     // SSNIT (Ghana social security)
     if (u.includes("SSNIT"))
-        return { icon: "🏛️", desc: "Enter your SSNIT number", requiresBack: false };
+        return { icon: "🏛️", desc: "Enter your SSNIT number", requiresBack: false };
     // Kenya National ID
     if (u.includes("KENYA") || (u.includes("NATIONAL") && u.includes("KENYA")))
-        return { icon: "🆔", desc: "Enter your Kenya National ID number", requiresBack: false };
+        return { icon: "🆔", desc: "Enter your Kenya National ID number", requiresBack: false };
     // TIN
     if (u.includes("TIN") || u.includes("TAX IDENTIFICATION"))
-        return { icon: "🧾", desc: "Enter your Tax Identification Number (TIN)", requiresBack: false };
+        return { icon: "🧾", desc: "Enter your Tax Identification Number (TIN)", requiresBack: false };
     // CAC / Company registration
     if (u.includes("CAC") || u.includes("CORPORATE AFFAIRS") || u.includes("COMPANY"))
-        return { icon: "🏢", desc: advanced ? "Enter RC number, company name & type" : "Enter your company registration number", requiresBack: false };
+        return { icon: "🏢", desc: advanced ? "Enter RC number, company name & type" : "Enter your company registration number", requiresBack: false };
     // Voter / PVC
     if (u.includes("VOTER") || u.includes("PVC")) {
         const requiresBack = requiresBackSide(typeName);
         return {
-            icon: "🗳️",
+            icon: "🗳️",
             desc: isDocumentFlow
                 ? `Capture or upload your voter's card${requiresBack ? " (front & back)" : ""}`
                 : "Enter your voter ID number",
@@ -93,12 +96,12 @@ function resolveIdTypeInfo(typeName, isDocumentFlow) {
     }
     // Passport
     if (u.includes("PASSPORT"))
-        return { icon: "📘", desc: isDocumentFlow ? "Capture or upload your passport" : "Enter your passport number", requiresBack: false };
+        return { icon: "📘", desc: isDocumentFlow ? "Capture or upload your passport" : "Enter your passport number", requiresBack: false };
     // Driver's license
     if (u.includes("DRIVER") || u.includes("LICENSE") || u.includes("LICENCE")) {
         const requiresBack = requiresBackSide(typeName);
         return {
-            icon: "🚗",
+            icon: "🚗",
             desc: isDocumentFlow
                 ? `Capture or upload your driver's license${requiresBack ? " (front & back)" : ""}`
                 : "Enter your driver's license number",
@@ -109,7 +112,7 @@ function resolveIdTypeInfo(typeName, isDocumentFlow) {
     if (u.includes("NATIONAL ID") || (u.includes("NATIONAL") && u.includes("CARD"))) {
         const requiresBack = requiresBackSide(typeName);
         return {
-            icon: "🪪",
+            icon: "🪪",
             desc: isDocumentFlow
                 ? `Capture or upload your ID card${requiresBack ? " (front & back)" : ""}`
                 : "Enter your National ID number",
@@ -118,16 +121,114 @@ function resolveIdTypeInfo(typeName, isDocumentFlow) {
     }
     // Face liveness / comparison
     if (u.includes("LIVENESS") || u.includes("FACE COMPARISON") || u.includes("FACE MATCH"))
-        return { icon: "🤳", desc: "We'll capture a short selfie video to verify you", requiresBack: false };
+        return { icon: "🤳", desc: "We'll capture a short selfie video to verify you", requiresBack: false };
     return {
-        icon: isDocumentFlow ? "📄" : "🆔",
+        icon: isDocumentFlow ? "📄" : "🆔",
         desc: isDocumentFlow ? "Capture or upload your document" : "Enter your ID number",
         requiresBack: false,
     };
 }
-// ─────────────────────────────────────────────────────────────────────
+// ─────────────────────────────────────────────────────────────────────
+// ── Widget-side message sanitizer ─────────────────────────────────────────────
+// Strips anything technical before showing text to the end user.
+// Keeps messages that are already written plainly in natural language.
+function _sanitizeUserMessage(raw) {
+    if (!raw)
+        return null;
+    const lower = raw.toLowerCase();
+    // Block anything that looks internal / technical
+    const blocklist = [
+        "smartcomply", "face comparison service", "session id", "session_id",
+        "provider", "ocr", "textract", "rekognition", "deepface",
+        "ivs", "celery", "exception", "traceback", "str(e)",
+        "error:", "failed:", "django", "python", "http ",
+        "comparison mode", "liveness mode", "callback",
+        "face_comparison", "face_match", "confidence_percentage",
+        "threshold_percentage", "polling_fallback", "resolved_by",
+    ];
+    for (const blocked of blocklist) {
+        if (lower.includes(blocked))
+            return null;
+    }
+    // Block snake_case (internal field names accidentally leaking through)
+    if (/[a-z]+_[a-z]+/.test(raw) && !/\s/.test(raw.trim()))
+        return null;
+    // Block anything starting with a lowercase letter (likely a code/key)
+    if (raw.trim()[0] === raw.trim()[0].toLowerCase() && /^[a-z]/.test(raw.trim()))
+        return null;
+    return raw.trim();
+}
+// ── B8: OCR date string normaliser ───────────────────────────────────────────
+// OCR providers return dates in wildly different formats. new Date(str) is
+// locale-dependent for anything other than ISO 8601 (YYYY-MM-DD), so we
+// attempt a set of known patterns before falling back to the native parser.
+function _parseOcrDate(raw) {
+    if (!raw)
+        return null;
+    const s = raw.trim();
+    // ISO 8601 or near-ISO  — try first, always unambiguous
+    if (/^\d{4}-\d{2}-\d{2}/.test(s))
+        return new Date(s.slice(0, 10));
+    // DD/MM/YYYY  or  DD-MM-YYYY
+    const dmy = s.match(/^(\d{2})[\/\-](\d{2})[\/\-](\d{4})/);
+    if (dmy)
+        return new Date(`${dmy[3]}-${dmy[2]}-${dmy[1]}`);
+    // MM/DD/YYYY  (US format — less common from OCR but possible)
+    const mdy = s.match(/^(\d{2})\/(\d{2})\/(\d{4})/);
+    if (mdy) {
+        // Heuristic: if "month" > 12 it must be day-first
+        if (parseInt(mdy[1], 10) > 12)
+            return new Date(`${mdy[3]}-${mdy[2]}-${mdy[1]}`);
+        return new Date(`${mdy[3]}-${mdy[1]}-${mdy[2]}`);
+    }
+    // DD Mon YYYY  e.g. "12 May 2029"  or  "12 MAY 2029"
+    const dMonY = s.match(/^(\d{1,2})\s+([A-Za-z]{3,})\s+(\d{4})/);
+    if (dMonY)
+        return new Date(`${dMonY[2]} ${dMonY[1]} ${dMonY[3]}`);
+    // Last resort: native parser
+    const d = new Date(s);
+    return isNaN(d.getTime()) ? null : d;
+}
+// ── W12: Image compression before document upload ────────────────────────────
+async function _compressImage(blob, maxWidth = 1600, quality = 0.85) {
+    try {
+        const bmp = await createImageBitmap(blob);
+        const scale = Math.min(1, maxWidth / bmp.width);
+        const w = Math.round(bmp.width * scale);
+        const h = Math.round(bmp.height * scale);
+        const canvas = document.createElement("canvas");
+        canvas.width = w;
+        canvas.height = h;
+        canvas.getContext("2d").drawImage(bmp, 0, 0, w, h);
+        bmp.close();
+        return await new Promise((res, rej) => canvas.toBlob(b => b ? res(b) : rej(new Error("Compression failed")), "image/jpeg", quality));
+    }
+    catch {
+        return blob; // fallback to original on any error
+    }
+}
+// ── Document type code → human label ─────────────────────────────────────────
+function _formatDocType(code) {
+    const map = {
+        passport: "Passport",
+        national_id: "National ID",
+        nin_slip: "NIN Slip",
+        nin_with_face: "National Identity Number",
+        drivers_license: "Driver's Licence",
+        voters_card: "Voter's Card",
+        kenya_id: "Kenya National ID",
+        ghana_id: "Ghana Card",
+    };
+    if (!code)
+        return "";
+    const key = code.toLowerCase().replace(/[\s-]/g, "_");
+    if (map[key])
+        return map[key];
+    // Fallback: title-case the code
+    return code.replace(/_/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
 // SmartComplyFlow
-// ─────────────────────────────────────────────────────────────────────
+// ─────────────────────────────────────────────────────────────────────
 // Add CSS animation keyframes for spin animations
 const style = document.createElement('style');
 style.textContent = `
@@ -168,6 +269,25 @@ class SmartComplyFlow {
         this.livenessEntryId = null;
         this.isDestroyed = false;
         this.headerBackBtn = null;
+        // Retry safety — max 3 confirmation rejections or liveness failures per session
+        this._confirmRetries = 0;
+        this._livenessFailures = 0;
+        // IVS result stored for confirm_identity screen
+        this._ivsName = "";
+        this._ivsGender = "";
+        // OCR result stored for document_confirm screen
+        this._ocrName = "";
+        this._ocrDocNumber = "";
+        this._ocrExpiry = "";
+        this._ocrFaceImageUrl = "";
+        this._ocrIsExpired = false;
+        this._ocrExpirySoon = false;
+        // Camera pre-warm stream (created during confirmation screen, used in liveness)
+        this._prewarmedStream = null;
+        // OCR gate poll timer — stored so it can be cancelled on navigation or close
+        this._ocrPollTimer = null;
+        // UI timeout from _startStatusPolling — stored so close() can cancel it
+        this._uiTimeoutId = null;
         // Session expiry
         this.sessionExpiryTimer = null;
         // Status polling (result screen)
@@ -207,6 +327,11 @@ class SmartComplyFlow {
     close() {
         this.isDestroyed = true;
         this.docCapture?.destroy();
+        // Release any pre-warmed camera stream
+        if (this._prewarmedStream) {
+            this._prewarmedStream.getTracks().forEach(t => t.stop());
+            this._prewarmedStream = null;
+        }
         if (this.sessionExpiryTimer) {
             clearTimeout(this.sessionExpiryTimer);
             this.sessionExpiryTimer = null;
@@ -215,13 +340,23 @@ class SmartComplyFlow {
             clearTimeout(this._pollStatusTimer);
             this._pollStatusTimer = null;
         }
+        // B6: cancel OCR gate poll timer
+        if (this._ocrPollTimer) {
+            clearTimeout(this._ocrPollTimer);
+            this._ocrPollTimer = null;
+        }
+        // P4: cancel result-screen UI timeout
+        if (this._uiTimeoutId) {
+            clearTimeout(this._uiTimeoutId);
+            this._uiTimeoutId = null;
+        }
         if (this.overlay) {
             this.overlay.style.opacity = "0";
             setTimeout(() => {
                 try {
                     this.overlay?.remove();
                 }
-                catch (_) { /* extension interference — safe to ignore */ }
+                catch (_) { /* extension interference — safe to ignore */ }
                 this.overlay = null;
                 this.modal = null;
                 this.contentArea = null;
@@ -229,9 +364,9 @@ class SmartComplyFlow {
         }
         this.options.onClose?.();
     }
-    // ─────────────────────────────────────────────────────────────────
+    // ─────────────────────────────────────────────────────────────────
     // Initialization
-    // ─────────────────────────────────────────────────────────────────
+    // ─────────────────────────────────────────────────────────────────
     mount() {
         // Inject keyframes
         this.injectStyles();
@@ -249,6 +384,9 @@ class SmartComplyFlow {
         // Modal
         this.modal = document.createElement("div");
         this.modal.id = "sc-flow-modal";
+        this.modal.setAttribute("role", "dialog");
+        this.modal.setAttribute("aria-modal", "true");
+        this.modal.setAttribute("aria-label", "Identity verification");
         this.modal.style.cssText = `
       width:100%;max-width:580px;max-height:95vh;
       background:${this.theme.bg};
@@ -274,6 +412,9 @@ class SmartComplyFlow {
         // Content area (scrollable)
         this.contentArea = document.createElement("div");
         this.contentArea.id = "sc-flow-content";
+        this.contentArea.setAttribute("role", "main");
+        this.contentArea.setAttribute("aria-live", "polite");
+        this.contentArea.setAttribute("aria-atomic", "false");
         this.contentArea.style.cssText = `
       flex:1;overflow-y:auto;padding:16px 20px;
       -webkit-overflow-scrolling:touch;
@@ -310,12 +451,12 @@ class SmartComplyFlow {
             }
             // Load config
             this.sdkConfig = await this.sdk.initializeConfig();
-            // Apply theme from config
+            // Apply theme from config — use theme_hex to override primary colour if set
             if (this.sdkConfig.theme) {
-                this.theme = (0, theme_1.getTheme)(this.sdkConfig.theme);
+                this.theme = (0, theme_1.getTheme)(this.sdkConfig.theme, this.sdkConfig.theme_hex || null);
                 this.applyTheme();
             }
-            // Update brand name
+            // Update brand name in header
             if (this.brandLabel && this.sdkConfig.brand_name) {
                 this.brandLabel.textContent = this.sdkConfig.brand_name;
             }
@@ -327,13 +468,18 @@ class SmartComplyFlow {
             this.showErrorStep(err.message || "Failed to initialize. Please try again.");
         }
     }
-    // ─────────────────────────────────────────────────────────────────
+    // ─────────────────────────────────────────────────────────────────
     // Step rendering
-    // ─────────────────────────────────────────────────────────────────
+    // ─────────────────────────────────────────────────────────────────
     showStep(step) {
         this.currentStep = step;
         if (!this.contentArea)
             return;
+        // P1/B6: cancel any in-flight OCR gate poll when user navigates away
+        if (this._ocrPollTimer) {
+            clearTimeout(this._ocrPollTimer);
+            this._ocrPollTimer = null;
+        }
         // Update progress
         this.updateProgress();
         // Animate out current content
@@ -371,20 +517,32 @@ class SmartComplyFlow {
             case "id_input":
                 this.renderIdInput(wrapper);
                 break;
+            case "confirm_identity":
+                this.renderConfirmIdentity(wrapper);
+                break;
             case "document_capture":
                 this.renderDocumentCapture(wrapper);
                 break;
+            case "ocr_gate":
+                this.renderOcrGate(wrapper);
+                break;
+            case "document_confirm":
+                this.renderDocumentConfirm(wrapper);
+                break;
             case "processing":
-                this.renderProcessing(wrapper);
+                // C1: processing step is dead code — flow now goes to 'done' after submit
                 break;
             case "liveness":
                 this.renderLiveness(wrapper);
                 break;
+            case "done":
+                this.renderDone(wrapper);
+                break;
             case "result":
-                this.renderResult(wrapper);
+                // C2: result step is dead code — showResult/renderResult removed
                 break;
             case "error":
-                break; // handled separately
+                break;
         }
         this.contentArea.appendChild(wrapper);
         // Animate in
@@ -393,7 +551,7 @@ class SmartComplyFlow {
             wrapper.style.transform = "translateX(0)";
         });
     }
-    // ── Loading ─────────────────────────────────────────────────────
+    // ── Loading ─────────────────────────────────────────────────────
     renderLoading(container) {
         container.style.cssText += "display:flex;flex-direction:column;align-items:center;justify-content:center;min-height:300px;gap:16px;";
         const spinnerWrap = document.createElement("div");
@@ -424,7 +582,7 @@ class SmartComplyFlow {
         sub.textContent = "Connecting to the verification service...";
         container.appendChild(sub);
     }
-    // ── Welcome ────────────────────────────────────────────────────
+    // ── Welcome ────────────────────────────────────────────────────
     renderWelcome(container) {
         container.style.cssText += "display:flex;flex-direction:column;align-items:center;text-align:center;gap:12px;";
         const isDocFlow = this.isDocumentFlow();
@@ -439,7 +597,7 @@ class SmartComplyFlow {
       background:linear-gradient(135deg,${this.theme.primary}22,${this.theme.primaryGlow});
       border:1.5px solid ${this.theme.primary}33;
     `;
-        iconWrap.textContent = isDocFlow ? "🪪" : "🛡️";
+        iconWrap.textContent = isDocFlow ? "🪪" : "🛡️";
         topRow.appendChild(iconWrap);
         const badge = document.createElement("div");
         badge.style.cssText = `
@@ -450,7 +608,7 @@ class SmartComplyFlow {
       color:${this.theme.primary};
       border:1px solid ${this.theme.primary}30;
     `;
-        badge.textContent = isDocFlow ? "📄  Document Verification" : "🔍  Data Verification";
+        badge.textContent = isDocFlow ? "📄  Document Verification" : "🔍  Data Verification";
         topRow.appendChild(badge);
         container.appendChild(topRow);
         // Title + subtitle (compact)
@@ -461,7 +619,11 @@ class SmartComplyFlow {
       color:${this.theme.text};font-size:20px;font-weight:700;
       margin:0;line-height:1.2;
     `;
-        title.textContent = "Identity Verification";
+        // W2: Use client brand name in title
+        const brandName = this.sdkConfig?.brand_name;
+        title.textContent = brandName
+            ? `Verify your identity for ${brandName}`
+            : "Identity Verification";
         titleWrap.appendChild(title);
         const desc = document.createElement("p");
         desc.style.cssText = `
@@ -469,21 +631,21 @@ class SmartComplyFlow {
       margin:0;max-width:300px;
     `;
         desc.textContent = isDocFlow
-            ? "Scan your ID document and take a quick selfie to confirm your identity."
-            : "Enter your ID details and take a quick selfie to confirm your identity.";
+            ? "You'll need your document and camera access. This takes about 2 minutes."
+            : "You'll need your ID number and camera access. This takes about 2 minutes.";
         titleWrap.appendChild(desc);
         container.appendChild(titleWrap);
-        // Steps preview — compact rows
+        // Steps preview — compact rows
         const steps = isDocFlow
             ? [
-                { icon: "🪪", text: "Choose your document type", sub: "Passport, National ID, Driver License" },
-                { icon: "📷", text: "Scan your document", sub: "Upload or capture a photo of your ID" },
-                { icon: "🤳", text: "Face check", sub: "Quick selfie to confirm it's you" },
+                { icon: "🪪", text: "Choose your document type", sub: "Passport, National ID, Driver License" },
+                { icon: "📷", text: "Scan your document", sub: "Upload or capture a photo of your ID" },
+                { icon: "🤳", text: "Face check", sub: "Quick selfie to confirm it's you" },
             ]
             : [
-                { icon: "🆔", text: "Choose your ID type", sub: "NIN, BVN, Voter's Card and more" },
-                { icon: "📝", text: "Enter your ID details", sub: "Exactly as shown on your ID" },
-                { icon: "🤳", text: "Face check", sub: "Quick selfie to confirm it's you" },
+                { icon: "🆔", text: "Choose your ID type", sub: "NIN, BVN, Voter's Card and more" },
+                { icon: "📝", text: "Enter your ID details", sub: "Exactly as shown on your ID" },
+                { icon: "🤳", text: "Face check", sub: "Quick selfie to confirm it's you" },
             ];
         const stepsWrap = document.createElement("div");
         stepsWrap.style.cssText = `
@@ -524,21 +686,21 @@ class SmartComplyFlow {
         });
         container.appendChild(stepsWrap);
         // CTA
-        const btn = this.createPrimaryButton("Get Started →");
+        const btn = this.createPrimaryButton("Get Started →");
         btn.style.cssText += "margin-top:2px;";
         btn.addEventListener("click", () => this.showStep("country"));
         container.appendChild(btn);
-        // Trust badge — "Powered by Adhere" already lives in the persistent
+        // Trust badge — "Powered by Adhere" already lives in the persistent
         // modal footer below; repeating it here just cost vertical space.
         const trust = document.createElement("div");
         trust.style.cssText = `
       display:flex;align-items:center;gap:6px;
       color:${this.theme.textMuted};font-size:10.5px;
     `;
-        trust.textContent = "🔒  End-to-end encrypted";
+        trust.textContent = "🔒  End-to-end encrypted";
         container.appendChild(trust);
     }
-    // ── Country Select ──────────────────────────────────────────────
+    // ── Country Select ──────────────────────────────────────────────
     renderCountrySelect(container) {
         container.style.cssText += "display:flex;flex-direction:column;gap:14px;";
         const channels = this.sdkConfig?.channels || {};
@@ -563,7 +725,7 @@ class SmartComplyFlow {
             container.appendChild(card);
         }
     }
-    // ── ID Type Select ──────────────────────────────────────────────
+    // ── ID Type Select ──────────────────────────────────────────────
     renderIdTypeSelect(container) {
         container.style.cssText += "display:flex;flex-direction:column;gap:14px;";
         const globalDocFlow = this.isDocumentFlow();
@@ -591,9 +753,9 @@ class SmartComplyFlow {
             // Add back side indicator to subtitle if needed
             let subtitle = info.desc;
             if (requiresBack && isThisDocFlow) {
-                subtitle += " ⚠️ Both sides required";
+                subtitle += " ⚠️ Both sides required";
             }
-            // Clean display name — strip "with face", "(NIN)", "(BVN)" from user-visible label
+            // Clean display name — strip "with face", "(NIN)", "(BVN)" from user-visible label
             const displayName = typeName
                 .replace(/\s*with\s+face\s*/gi, ' ')
                 .replace(/\s*\(NIN\)\s*/gi, ' ')
@@ -630,7 +792,7 @@ class SmartComplyFlow {
             container.appendChild(card);
         }
     }
-    // ── ID Input (data verification — dynamic fields) ─────────────
+    // ── ID Input (data verification — dynamic fields) ─────────────
     renderIdInput(container) {
         container.style.cssText += "display:flex;flex-direction:column;gap:14px;";
         const dataFields = this.selectedChannelFields.filter((f) => f.type !== "upload");
@@ -649,7 +811,7 @@ class SmartComplyFlow {
             ? `Enter your ${this.selectedIdTypeName || this.selectedIdType} details exactly as they appear on your ID.`
             : "Fill in the fields below to continue.";
         container.appendChild(subtitle);
-        // Edge case: no data fields configured — show fallback and allow submission
+        // Edge case: no data fields configured — show fallback and allow submission
         if (dataFields.length === 0) {
             const empty = document.createElement("div");
             empty.style.cssText = `
@@ -664,10 +826,45 @@ class SmartComplyFlow {
             container.appendChild(autoBtn);
             return;
         }
+        const _FIELD_RULES = [
+            { match: "BVN", rule: { minLen: 11, maxLen: 11, numeric: true, hint: "BVN must be exactly 11 digits" } },
+            { match: "NIN", rule: { minLen: 11, maxLen: 11, numeric: true, hint: "NIN must be exactly 11 digits" } },
+            { match: "NATIONAL IDENTITY", rule: { minLen: 11, maxLen: 11, numeric: true, hint: "NIN must be exactly 11 digits" } },
+            { match: "PASSPORT", rule: { minLen: 6, maxLen: 20, alphanumeric: true, hint: "Passport number must be 6–20 alphanumeric characters" } },
+            { match: "DRIVER", rule: { minLen: 3, maxLen: 30, alphanumeric: true, hint: "Licence number must be 3–30 alphanumeric characters" } },
+            { match: "VOTER", rule: { minLen: 6, maxLen: 30, alphanumeric: true, hint: "Voter ID must be 6–30 alphanumeric characters" } },
+            { match: "GHANA", rule: { minLen: 8, maxLen: 20, alphanumeric: true, hint: "Ghana Card number must be 8–20 alphanumeric characters" } },
+            { match: "SSNIT", rule: { minLen: 7, maxLen: 15, alphanumeric: true, hint: "SSNIT number must be 7–15 alphanumeric characters" } },
+            { match: "TIN", rule: { minLen: 8, maxLen: 20, alphanumeric: true, hint: "TIN must be 8–20 characters" } },
+            { match: "KRA", rule: { minLen: 10, maxLen: 12, alphanumeric: true, hint: "KRA PIN must be 10–12 characters" } },
+        ];
+        function getFieldRule(label) {
+            const upper = label.toUpperCase();
+            for (const entry of _FIELD_RULES) {
+                if (upper.includes(entry.match))
+                    return entry.rule;
+            }
+            return null;
+        }
+        function validateFieldValue(label, value) {
+            const rule = getFieldRule(label);
+            if (!rule)
+                return null; // no rule = no validation
+            const v = value.trim();
+            if (rule.numeric && !/^\d+$/.test(v))
+                return `${label} must contain digits only`;
+            if (rule.alphanumeric && !/^[A-Za-z0-9]+$/.test(v))
+                return `${label} must be alphanumeric (letters and digits only)`;
+            if (rule.minLen && v.length < rule.minLen)
+                return rule.hint;
+            if (rule.maxLen && v.length > rule.maxLen)
+                return rule.hint;
+            return null;
+        }
         // Track input elements for validation
         const inputEls = [];
         for (const field of dataFields) {
-            // Send the raw label as the payload key — the backend's
+            // Send the raw label as the payload key — the backend's
             // _SDK_FIELD_KEY_MAP looks up the exact label text (e.g. "National ID",
             // "CAC Number") to remap it to the canonical IVS key. Pre-normalizing
             // it here (as this used to do) produced keys like "national_id" that
@@ -676,7 +873,10 @@ class SmartComplyFlow {
             const fieldKey = field.label;
             const fieldWrap = document.createElement("div");
             fieldWrap.style.cssText = "display:flex;flex-direction:column;gap:6px;";
+            const labelId = `sc-field-label-${fieldKey.replace(/\s+/g, '-').toLowerCase()}`;
             const label = document.createElement("label");
+            label.id = labelId;
+            label.htmlFor = `sc-field-input-${fieldKey.replace(/\s+/g, '-').toLowerCase()}`;
             label.style.cssText = `color:${this.theme.textMuted};font-size:10px;font-weight:700;letter-spacing:0.6px;text-transform:uppercase;`;
             label.textContent = field.label;
             fieldWrap.appendChild(label);
@@ -714,7 +914,7 @@ class SmartComplyFlow {
                 inputEls.push({ field, el: select });
             }
             else if (field.type === "image" || field.type === "file") {
-                // File upload field — converts to base64 for API submission
+                // File upload field — converts to base64 for API submission
                 const fileInput = document.createElement("input");
                 fileInput.type = "file";
                 fileInput.accept = "image/*";
@@ -750,10 +950,18 @@ class SmartComplyFlow {
             }
             else {
                 // Text input field
+                const inputId = `sc-field-input-${fieldKey.replace(/\s+/g, '-').toLowerCase()}`;
+                const hintId = `sc-field-hint-${fieldKey.replace(/\s+/g, '-').toLowerCase()}`;
+                const rule = getFieldRule(field.label);
                 const input = document.createElement("input");
                 input.type = "text";
+                input.id = inputId;
+                input.setAttribute("aria-labelledby", labelId);
+                input.setAttribute("aria-describedby", hintId);
                 input.placeholder = `Enter ${field.label}`;
-                input.maxLength = 50;
+                input.maxLength = rule?.maxLen ? rule.maxLen + 2 : 50;
+                if (rule?.numeric)
+                    input.inputMode = "numeric";
                 input.style.cssText = `
           width:100%;padding:14px 16px;border-radius:12px;
           font-size:16px;font-weight:500;
@@ -764,17 +972,50 @@ class SmartComplyFlow {
           box-sizing:border-box;
           letter-spacing:0.5px;
         `;
+                // Inline hint/error element
+                const hintEl = document.createElement("div");
+                hintEl.id = hintId;
+                hintEl.setAttribute("aria-live", "polite");
+                hintEl.style.cssText = `font-size:11px;min-height:14px;margin-top:-2px;`;
+                if (rule) {
+                    hintEl.style.color = this.theme.textMuted;
+                    hintEl.textContent = rule.hint;
+                }
                 input.addEventListener("focus", () => {
                     input.style.borderColor = this.theme.primary;
                 });
                 input.addEventListener("blur", () => {
-                    input.style.borderColor = this.theme.border;
+                    const v = input.value.trim();
+                    if (v) {
+                        const err = validateFieldValue(field.label, v);
+                        if (err) {
+                            input.style.borderColor = this.theme.error;
+                            hintEl.style.color = this.theme.error;
+                            hintEl.textContent = err;
+                            input.setAttribute("aria-invalid", "true");
+                        }
+                        else {
+                            input.style.borderColor = this.theme.success || this.theme.primary;
+                            hintEl.style.color = this.theme.textMuted;
+                            hintEl.textContent = rule?.hint || "";
+                            input.setAttribute("aria-invalid", "false");
+                        }
+                    }
+                    else {
+                        input.style.borderColor = this.theme.border;
+                    }
                 });
                 input.addEventListener("input", () => {
+                    // Reset error styling while typing
+                    input.style.borderColor = this.theme.primary;
+                    hintEl.style.color = this.theme.textMuted;
+                    hintEl.textContent = rule?.hint || "";
+                    input.removeAttribute("aria-invalid");
                     this.collectedFields[fieldKey] = input.value.trim();
                     updateSubmitState();
                 });
                 fieldWrap.appendChild(input);
+                fieldWrap.appendChild(hintEl);
                 inputEls.push({ field, el: input });
             }
             container.appendChild(fieldWrap);
@@ -792,9 +1033,16 @@ class SmartComplyFlow {
         submitBtn.disabled = true;
         submitBtn.style.opacity = "0.5";
         const updateSubmitState = () => {
+            // All inputs must have a value AND pass format validation
             const allFilled = inputEls.every(({ el }) => el.value.trim().length > 0);
-            submitBtn.disabled = !allFilled;
-            submitBtn.style.opacity = allFilled ? "1" : "0.5";
+            const allValid = inputEls.every(({ field, el }) => {
+                if (el.tagName === "SELECT")
+                    return el.value.trim().length > 0;
+                return !validateFieldValue(field.label, el.value.trim());
+            });
+            const ok = allFilled && allValid;
+            submitBtn.disabled = !ok;
+            submitBtn.style.opacity = ok ? "1" : "0.5";
         };
         submitBtn.addEventListener("click", async () => {
             submitBtn.disabled = true;
@@ -806,15 +1054,21 @@ class SmartComplyFlow {
                     fields: { ...this.collectedFields },
                 });
                 if (this.verificationResult.status === "success") {
-                    // Save the first collected field value as identifier for liveness
+                    // Save identifier and identity_check_id for liveness step
                     const fieldValues = Object.values(this.collectedFields);
                     this.idNumber = fieldValues[0] || "";
-                    // A4: Save identity_check_id from verify response to pass to liveness
                     this.identityCheckId = this.verificationResult.data?.identity_check_id || null;
-                    this.showStep("liveness");
+                    // W3: Store name + gender from IVS result for confirmation screen
+                    const d = this.verificationResult.data || {};
+                    const nd = d.normalized_data || d.data || d;
+                    this._ivsName = [nd.first_name || nd.firstname || "", nd.last_name || nd.lastname || nd.surname || ""]
+                        .map(s => String(s || "").trim()).filter(Boolean).join(" ");
+                    this._ivsGender = nd.gender || "";
+                    // Route to confirmation screen — user must confirm before liveness
+                    this.showStep("confirm_identity");
                 }
                 else {
-                    errorEl.textContent = this.verificationResult.message || "Verification failed. Please check your details.";
+                    errorEl.textContent = this.verificationResult.message || "We could not verify your details. Please check and try again.";
                     errorEl.style.display = "block";
                     submitBtn.textContent = "Verify & Continue";
                     submitBtn.disabled = false;
@@ -822,14 +1076,26 @@ class SmartComplyFlow {
                 }
             }
             catch (err) {
-                // C3: Show field-level errors if available
+                // Show a single plain-language error — never raw field:message format
                 const fieldErrors = err.data?.errors;
                 if (Array.isArray(fieldErrors) && fieldErrors.length > 0) {
-                    const messages = fieldErrors.map((e) => `${e.field}: ${e.message}`).join("\n");
-                    errorEl.textContent = messages;
+                    // Pick the first meaningful error message — strip field prefix
+                    const firstMsg = fieldErrors[0]?.message || fieldErrors[0]?.detail || "";
+                    errorEl.textContent = _sanitizeUserMessage(firstMsg)
+                        || "Please check your details and try again.";
+                }
+                else if (err.code === "VERIFICATION_FAILED") {
+                    errorEl.textContent = "We could not verify those details. Please check your ID number and try again.";
+                }
+                else if (err.code === "CHANNEL_NOT_CONFIGURED") {
+                    errorEl.textContent = "This ID type is not currently available. Please choose a different option.";
+                }
+                else if (err.code === "INSUFFICIENT_BALANCE") {
+                    errorEl.textContent = "Verification is temporarily unavailable. Please contact support.";
                 }
                 else {
-                    errorEl.textContent = err.message || "Verification failed";
+                    errorEl.textContent = _sanitizeUserMessage(err.message)
+                        || "Something went wrong. Please try again.";
                 }
                 errorEl.style.display = "block";
                 submitBtn.textContent = "Verify & Continue";
@@ -844,7 +1110,7 @@ class SmartComplyFlow {
             setTimeout(() => firstInput.focus(), 350);
         }
     }
-    // ── Document Capture ────────────────────────────────────────────
+    // ── Document Capture ────────────────────────────────────────────
     renderDocumentCapture(container) {
         container.style.cssText += "display:flex;flex-direction:column;gap:14px;";
         // Strip "with face", "(NIN)", "(BVN)" noise from the user-visible title
@@ -885,144 +1151,408 @@ class SmartComplyFlow {
             this.showErrorStep(err.message || "Document capture failed. Please try again.");
         });
     }
-    // ── Processing ────────────────────────────────────────────────────
-    renderProcessing(container) {
-        // Compact layout — fits modal without scroll
-        container.style.cssText += "display:flex;flex-direction:column;align-items:center;gap:14px;padding:16px;";
-        // Small spinner
-        const animationWrap = document.createElement("div");
-        animationWrap.style.cssText = "position:relative;width:52px;height:52px;flex-shrink:0;";
-        const spinner = document.createElement("div");
-        spinner.style.cssText = `
-      position:absolute;inset:0;border-radius:50%;
-      border:3px solid ${this.theme.border};
-      border-top-color:${this.theme.primary};
-      animation:sc-spin 0.9s linear infinite;
-    `;
-        animationWrap.appendChild(spinner);
-        const centerIcon = document.createElement("div");
-        centerIcon.style.cssText = `
-      position:absolute;inset:0;display:flex;align-items:center;justify-content:center;
-      font-size:20px;
-    `;
-        centerIcon.textContent = "🔍";
-        animationWrap.appendChild(centerIcon);
-        container.appendChild(animationWrap);
-        const title = document.createElement("div");
-        title.style.cssText = `color:${this.theme.text};font-size:15px;font-weight:700;text-align:center;`;
-        title.textContent = "Processing your document";
+    // ── W3: Identity Confirmation (data verification) ───────────────
+    renderConfirmIdentity(container) {
+        container.style.cssText += "display:flex;flex-direction:column;align-items:center;text-align:center;gap:16px;padding:8px 0;";
+        // W14: Check retry limit before showing screen
+        if (this._confirmRetries >= SmartComplyFlow.MAX_RETRIES) {
+            this._renderRetryLimitReached(container);
+            return;
+        }
+        // W13: Pre-warm camera silently while user reads this screen
+        this._prewarmCamera();
+        const iconWrap = document.createElement("div");
+        iconWrap.style.cssText = `width:64px;height:64px;border-radius:50%;background:${this.theme.primary}15;border:2px solid ${this.theme.primary}30;display:flex;align-items:center;justify-content:center;font-size:28px;`;
+        iconWrap.textContent = "🛡️";
+        container.appendChild(iconWrap);
+        const title = document.createElement("h2");
+        title.style.cssText = `color:${this.theme.text};font-size:18px;font-weight:700;margin:0;`;
+        title.textContent = this._ivsName ? `Is this you?` : "Identity Confirmed";
         container.appendChild(title);
-        const subtitle = document.createElement("div");
-        subtitle.style.cssText = `color:${this.theme.textSecondary};font-size:12px;text-align:center;max-width:260px;line-height:1.5;`;
-        subtitle.textContent = "Scanning and verifying your ID. This usually takes a few seconds.";
-        container.appendChild(subtitle);
-        // Compact steps — 2-col grid so they fit without scroll
-        const stepsContainer = document.createElement("div");
-        stepsContainer.style.cssText = `
-      width:100%;display:grid;grid-template-columns:1fr 1fr;gap:8px;
-    `;
-        const steps = [
-            { id: 'uploading', text: 'Uploading', icon: '📤' },
-            { id: 'scanning', text: 'Scanning', icon: '🔍' },
-            { id: 'verifying', text: 'Verifying', icon: '✓' },
-            { id: 'analyzing', text: 'Checking quality', icon: '🔬' },
-        ];
-        steps.forEach((step) => {
-            const stepEl = document.createElement("div");
-            stepEl.style.cssText = `
-        display:flex;align-items:center;gap:8px;padding:9px 10px;border-radius:10px;
-        background:${this.theme.cardBg};border:1px solid ${this.theme.border};
-        transition:all 0.3s ease;
-      `;
-            stepEl.id = `processing-step-${step.id}`;
-            const iconEl = document.createElement("div");
-            iconEl.style.cssText = `
-        width:26px;height:26px;border-radius:7px;flex-shrink:0;
-        display:flex;align-items:center;justify-content:center;
-        font-size:12px;background:${this.theme.shimmer};
-      `;
-            iconEl.textContent = step.icon;
-            iconEl.id = `step-icon-${step.id}`;
-            const textEl = document.createElement("div");
-            textEl.style.cssText = `flex:1;color:${this.theme.textSecondary};font-size:11px;font-weight:500;`;
-            textEl.textContent = step.text;
-            textEl.id = `step-text-${step.id}`;
-            const statusEl = document.createElement("div");
-            statusEl.style.cssText = `width:16px;height:16px;border-radius:50%;border:2px solid ${this.theme.border};position:relative;flex-shrink:0;`;
-            statusEl.id = `step-status-${step.id}`;
-            stepEl.appendChild(iconEl);
-            stepEl.appendChild(textEl);
-            stepEl.appendChild(statusEl);
-            stepsContainer.appendChild(stepEl);
+        if (this._ivsName) {
+            // Profile card
+            const card = document.createElement("div");
+            card.style.cssText = `width:100%;padding:16px;border-radius:14px;background:${this.theme.cardBg};border:1.5px solid ${this.theme.border};text-align:left;display:flex;flex-direction:column;gap:10px;`;
+            const rows = [
+                { label: "Name", value: this._ivsName },
+            ];
+            if (this._ivsGender) {
+                const gLabel = this._ivsGender.toLowerCase();
+                rows.push({ label: "Gender", value: gLabel === "m" || gLabel === "male" || gLabel === "1" ? "Male" : gLabel === "f" || gLabel === "female" || gLabel === "2" ? "Female" : this._ivsGender });
+            }
+            rows.push({ label: "ID Type", value: _formatDocType(this.selectedIdType) || this.selectedIdTypeName || this.selectedIdType });
+            rows.forEach(({ label, value }) => {
+                const row = document.createElement("div");
+                row.style.cssText = "display:flex;justify-content:space-between;align-items:center;";
+                const lEl = document.createElement("span");
+                lEl.style.cssText = `color:${this.theme.textMuted};font-size:12px;font-weight:500;`;
+                lEl.textContent = label;
+                const vEl = document.createElement("span");
+                vEl.style.cssText = `color:${this.theme.text};font-size:13px;font-weight:600;max-width:60%;text-align:right;`;
+                vEl.textContent = value;
+                row.appendChild(lEl);
+                row.appendChild(vEl);
+                card.appendChild(row);
+            });
+            container.appendChild(card);
+        }
+        else {
+            const sub = document.createElement("p");
+            sub.style.cssText = `color:${this.theme.textSecondary};font-size:13px;margin:0;max-width:280px;line-height:1.6;`;
+            sub.textContent = "Your details have been confirmed. Please continue to the face check.";
+            container.appendChild(sub);
+        }
+        const yesBtn = this.createPrimaryButton("Yes, that's me — continue");
+        yesBtn.addEventListener("click", () => {
+            // B5: Reset retry counter on successful confirmation
+            this._confirmRetries = 0;
+            this.showStep("liveness");
+        });
+        container.appendChild(yesBtn);
+        const noBtn = this.createSecondaryButton("No, use a different ID");
+        noBtn.addEventListener("click", () => {
+            this._confirmRetries++;
+            this._ivsName = "";
+            this._ivsGender = "";
+            this.identityCheckId = null;
+            this.verificationResult = null;
+            this.showStep("id_input");
         });
-        container.appendChild(stepsContainer);
-        this.startProcessingAnimation();
+        container.appendChild(noBtn);
     }
-    startProcessingAnimation() {
-        const steps = ['uploading', 'scanning', 'verifying', 'analyzing'];
-        let currentStepIndex = 0;
-        const animateStep = (stepId) => {
-            // Update step appearance
-            const stepEl = document.getElementById(`processing-step-${stepId}`);
-            const iconEl = document.getElementById(`step-icon-${stepId}`);
-            const textEl = document.getElementById(`step-text-${stepId}`);
-            const statusEl = document.getElementById(`step-status-${stepId}`);
-            if (stepEl && iconEl && textEl && statusEl) {
-                // Active state
-                stepEl.style.borderColor = this.theme.primary;
-                stepEl.style.background = `${this.theme.primary}10`;
-                iconEl.style.background = this.theme.primary;
-                iconEl.style.color = 'white';
-                textEl.style.color = this.theme.text;
-                textEl.style.fontWeight = '600';
-                // Add spinner to status
-                statusEl.innerHTML = `
-          <div style="
-            position:absolute;inset:2px;border-radius:50%;
-            border:2px solid ${this.theme.border};
-            border-top-color:${this.theme.primary};
-            animation:sc-spin 0.8s linear infinite;
-          "></div>
-        `;
+    // ── W4: Document Confirmation (document verification) ────────────
+    renderDocumentConfirm(container) {
+        container.style.cssText += "display:flex;flex-direction:column;align-items:center;text-align:center;gap:14px;padding:8px 0;";
+        // W14: Check retry limit
+        if (this._confirmRetries >= SmartComplyFlow.MAX_RETRIES) {
+            this._renderRetryLimitReached(container);
+            return;
+        }
+        // W13: Pre-warm camera while user reads
+        this._prewarmCamera();
+        const iconWrap = document.createElement("div");
+        iconWrap.style.cssText = `width:64px;height:64px;border-radius:50%;background:${this.theme.primary}15;border:2px solid ${this.theme.primary}30;display:flex;align-items:center;justify-content:center;font-size:28px;`;
+        iconWrap.textContent = "📄";
+        container.appendChild(iconWrap);
+        const title = document.createElement("h2");
+        title.style.cssText = `color:${this.theme.text};font-size:18px;font-weight:700;margin:0;`;
+        title.textContent = "Are these your details?";
+        container.appendChild(title);
+        const sub = document.createElement("p");
+        sub.style.cssText = `color:${this.theme.textSecondary};font-size:13px;margin:0;max-width:280px;line-height:1.5;`;
+        sub.textContent = "We read the following from your document. Please confirm they are correct before continuing.";
+        container.appendChild(sub);
+        // Document face thumbnail if available
+        if (this._ocrFaceImageUrl) {
+            const faceWrap = document.createElement("div");
+            faceWrap.style.cssText = `width:80px;height:80px;border-radius:50%;overflow:hidden;border:3px solid ${this.theme.primary};flex-shrink:0;margin:0 auto;`;
+            const faceImg = document.createElement("img");
+            faceImg.src = this._ocrFaceImageUrl;
+            faceImg.alt = "Photo from your document";
+            faceImg.style.cssText = "width:100%;height:100%;object-fit:cover;";
+            faceWrap.appendChild(faceImg);
+            container.appendChild(faceWrap);
+        }
+        // Expiry soon warning
+        if (this._ocrExpirySoon && !this._ocrIsExpired) {
+            const warn = document.createElement("div");
+            warn.style.cssText = `width:100%;padding:10px 14px;border-radius:10px;background:${this.theme.warning}18;border:1px solid ${this.theme.warning}40;color:${this.theme.warning};font-size:12px;text-align:left;line-height:1.5;`;
+            warn.textContent = "⚠️  Your document expires soon. Some services may not accept it, but you can still continue.";
+            container.appendChild(warn);
+        }
+        // Details card — show whatever OCR returned, never block on missing fields
+        const card = document.createElement("div");
+        card.style.cssText = `width:100%;padding:14px 16px;border-radius:14px;background:${this.theme.cardBg};border:1.5px solid ${this.theme.border};text-align:left;display:flex;flex-direction:column;gap:10px;`;
+        const docRows = [];
+        if (this._ocrName)
+            docRows.push({ label: "Name", value: this._ocrName });
+        if (this._ocrDocNumber)
+            docRows.push({ label: "Document No", value: this._ocrDocNumber });
+        if (this._ocrExpiry)
+            docRows.push({ label: "Expires", value: this._ocrExpiry });
+        docRows.push({ label: "Document Type", value: _formatDocType(this.selectedIdType) || this.selectedIdTypeName });
+        if (docRows.length === 0) {
+            const fallback = document.createElement("div");
+            fallback.style.cssText = `color:${this.theme.textSecondary};font-size:12px;`;
+            fallback.textContent = "Document scanned successfully.";
+            card.appendChild(fallback);
+        }
+        else {
+            docRows.forEach(({ label, value }) => {
+                if (!value)
+                    return;
+                const row = document.createElement("div");
+                row.style.cssText = "display:flex;justify-content:space-between;align-items:center;";
+                const lEl = document.createElement("span");
+                lEl.style.cssText = `color:${this.theme.textMuted};font-size:12px;font-weight:500;`;
+                lEl.textContent = label;
+                const vEl = document.createElement("span");
+                vEl.style.cssText = `color:${this.theme.text};font-size:13px;font-weight:600;max-width:60%;text-align:right;`;
+                vEl.textContent = value;
+                row.appendChild(lEl);
+                row.appendChild(vEl);
+                card.appendChild(row);
+            });
+        }
+        container.appendChild(card);
+        const yesBtn = this.createPrimaryButton("Yes, continue");
+        yesBtn.addEventListener("click", () => {
+            // B5: Reset retry counter on successful confirmation
+            this._confirmRetries = 0;
+            this.showStep("liveness");
+        });
+        container.appendChild(yesBtn);
+        const noBtn = this.createSecondaryButton("No, retake document");
+        noBtn.addEventListener("click", () => {
+            this._confirmRetries++;
+            this._ocrName = "";
+            this._ocrDocNumber = "";
+            this._ocrExpiry = "";
+            this._ocrFaceImageUrl = "";
+            this._ocrIsExpired = false;
+            this._ocrExpirySoon = false;
+            this.livenessEntryId = null;
+            this.documentBlob = null;
+            this.documentBackBlob = null;
+            this.showStep("document_capture");
+        });
+        container.appendChild(noBtn);
+    }
+    // ── W6+W7+W8: OCR Gate (document verification) ───────────────────
+    renderOcrGate(container) {
+        container.style.cssText += "display:flex;flex-direction:column;align-items:center;gap:14px;padding:20px 0;text-align:center;";
+        const spinnerWrap = document.createElement("div");
+        spinnerWrap.style.cssText = "position:relative;width:52px;height:52px;flex-shrink:0;";
+        const ring = document.createElement("div");
+        ring.style.cssText = `position:absolute;inset:0;border-radius:50%;border:3px solid ${this.theme.border};border-top-color:${this.theme.primary};animation:sc-spin 0.9s linear infinite;`;
+        const centre = document.createElement("div");
+        centre.style.cssText = "position:absolute;inset:0;display:flex;align-items:center;justify-content:center;font-size:20px;";
+        centre.textContent = "📄";
+        spinnerWrap.appendChild(ring);
+        spinnerWrap.appendChild(centre);
+        container.appendChild(spinnerWrap);
+        const statusEl = document.createElement("div");
+        statusEl.setAttribute("aria-live", "polite");
+        statusEl.style.cssText = `color:${this.theme.text};font-size:15px;font-weight:600;`;
+        statusEl.textContent = "Reading your document…";
+        container.appendChild(statusEl);
+        const subEl = document.createElement("div");
+        subEl.style.cssText = `color:${this.theme.textSecondary};font-size:12px;max-width:260px;line-height:1.5;`;
+        subEl.textContent = "This usually takes 5–15 seconds. Please wait.";
+        container.appendChild(subEl);
+        if (!this.livenessEntryId) {
+            this.showErrorStep("Document upload failed. Please try again.");
+            return;
+        }
+        const entryId = this.livenessEntryId;
+        const MAX_POLLS = 10; // 10 × 2s = 20s timeout
+        let polls = 0;
+        const poll = async () => {
+            if (this.isDestroyed)
+                return;
+            polls++;
+            try {
+                const result = await this.sdk.liveness.pollResult(entryId);
+                // W7: Expired document — stop, do not proceed to liveness
+                if (result.is_expired === true) {
+                    container.innerHTML = "";
+                    this._renderExpiredDocument(container);
+                    return;
+                }
+                // W8: OCR quality fail — offer retake
+                if (result.ocr_quality_failed === true) {
+                    container.innerHTML = "";
+                    this._renderOcrQualityFail(container, result.ocr_rejection_reason);
+                    return;
+                }
+                // OCR complete — store data and show confirmation screen
+                const ocrDone = result.ocr_status === "done" || result.ocr_status === "ocr_complete"
+                    || result.ocr_name || result.ocr_document_number || result.ocr_expiry_date;
+                if (ocrDone) {
+                    this._ocrName = result.ocr_name || "";
+                    this._ocrDocNumber = result.ocr_document_number || "";
+                    this._ocrExpiry = result.ocr_expiry_date || "";
+                    this._ocrFaceImageUrl = result.ocr_face_image_url || "";
+                    this._ocrIsExpired = result.is_expired === true;
+                    // B8: Normalise expiry date string before parsing — OCR may return
+                    // DD/MM/YYYY, DD-MM-YYYY, YYYY-MM-DD, or "12 May 2029" etc.
+                    // new Date() alone is locale-dependent on non-ISO strings.
+                    if (this._ocrExpiry) {
+                        const expDate = _parseOcrDate(this._ocrExpiry);
+                        if (expDate) {
+                            const sixMonths = new Date();
+                            sixMonths.setMonth(sixMonths.getMonth() + 6);
+                            this._ocrExpirySoon = expDate <= sixMonths && expDate > new Date();
+                        }
+                    }
+                    this.showStep("document_confirm");
+                    return;
+                }
+                // Still pending — keep polling
+                if (polls < MAX_POLLS && !this.isDestroyed) {
+                    this._ocrPollTimer = setTimeout(poll, 2000);
+                }
+                else if (!this.isDestroyed) {
+                    // Timeout — proceed anyway with whatever we have
+                    statusEl.textContent = "Taking longer than usual…";
+                    subEl.textContent = "We'll continue — you can confirm your details on the next screen.";
+                    this._ocrPollTimer = setTimeout(() => {
+                        if (!this.isDestroyed)
+                            this.showStep("document_confirm");
+                    }, 2000);
+                }
             }
-            // Move to next step after delay
-            setTimeout(() => {
-                // Complete current step
-                if (stepEl && iconEl && textEl && statusEl) {
-                    stepEl.style.borderColor = this.theme.success;
-                    stepEl.style.background = `${this.theme.success}10`;
-                    iconEl.style.background = this.theme.success;
-                    statusEl.innerHTML = `
-            <div style="
-              position:absolute;inset:3px;border-radius:50%;
-              background:${this.theme.success};
-              display:flex;align-items:center;justify-content:center;
-              color:white;font-size:10px;font-weight:bold;
-            ">✓</div>
-          `;
+            catch {
+                if (polls < MAX_POLLS && !this.isDestroyed) {
+                    this._ocrPollTimer = setTimeout(poll, 3000);
                 }
-                currentStepIndex++;
-                if (currentStepIndex < steps.length) {
-                    animateStep(steps[currentStepIndex]);
+                else if (!this.isDestroyed) {
+                    this.showErrorStep("We could not read your document. Please check your connection and try again.");
                 }
-            }, 2000); // 2 seconds per step
+            }
         };
-        // Start animation
-        setTimeout(() => animateStep(steps[0]), 500);
+        // First poll after 3s — give OCR submission time to start
+        this._ocrPollTimer = setTimeout(poll, 3000);
+    }
+    _renderExpiredDocument(container) {
+        container.style.cssText += "display:flex;flex-direction:column;align-items:center;text-align:center;gap:14px;padding:20px 0;";
+        const icon = document.createElement("div");
+        icon.style.cssText = `width:72px;height:72px;border-radius:50%;background:${this.theme.errorBg};border:3px solid ${this.theme.error};display:flex;align-items:center;justify-content:center;font-size:28px;`;
+        icon.textContent = "📅";
+        container.appendChild(icon);
+        const t = document.createElement("h2");
+        t.style.cssText = `color:${this.theme.text};font-size:18px;font-weight:700;margin:0;`;
+        t.textContent = "Document Expired";
+        container.appendChild(t);
+        const d = document.createElement("p");
+        d.style.cssText = `color:${this.theme.textSecondary};font-size:13px;margin:0;max-width:280px;line-height:1.6;`;
+        d.textContent = "The document you submitted has expired. Please use a valid, current ID.";
+        container.appendChild(d);
+        const retryBtn = this.createPrimaryButton("Try a different document");
+        retryBtn.addEventListener("click", () => {
+            this.livenessEntryId = null;
+            this.documentBlob = null;
+            this.documentBackBlob = null;
+            this.showStep("document_capture");
+        });
+        container.appendChild(retryBtn);
+        const endBtn = this.createSecondaryButton("End session");
+        endBtn.addEventListener("click", () => { this.options.onError?.(new Error("Document expired")); this.close(); });
+        container.appendChild(endBtn);
+    }
+    _renderOcrQualityFail(container, reason) {
+        container.style.cssText += "display:flex;flex-direction:column;align-items:center;text-align:center;gap:14px;padding:20px 0;";
+        const icon = document.createElement("div");
+        icon.style.cssText = `width:72px;height:72px;border-radius:50%;background:${this.theme.errorBg};border:3px solid ${this.theme.error};display:flex;align-items:center;justify-content:center;font-size:28px;`;
+        icon.textContent = "🔍";
+        container.appendChild(icon);
+        const t = document.createElement("h2");
+        t.style.cssText = `color:${this.theme.text};font-size:18px;font-weight:700;margin:0;`;
+        t.textContent = "Document Photo Unclear";
+        container.appendChild(t);
+        const msg = reason === "image_too_blurry" ? "Your document photo is too blurry. Please retake it in good lighting with a steady hand."
+            : reason === "image_too_dark" ? "Your document photo is too dark. Please retake it in better lighting."
+                : reason === "image_too_bright" ? "Your document photo has too much glare. Please reduce reflections and retake."
+                    : reason === "document_not_detected" ? "We could not detect a document in the photo. Please ensure the full ID is visible."
+                        : "We could not read your document clearly. Please retake the photo in good lighting with no glare.";
+        const d = document.createElement("p");
+        d.style.cssText = `color:${this.theme.textSecondary};font-size:13px;margin:0;max-width:280px;line-height:1.6;`;
+        d.textContent = msg;
+        container.appendChild(d);
+        const retryBtn = this.createPrimaryButton("Retake photo");
+        retryBtn.addEventListener("click", () => {
+            this.livenessEntryId = null;
+            this.documentBlob = null;
+            this.documentBackBlob = null;
+            this.showStep("document_capture");
+        });
+        container.appendChild(retryBtn);
+    }
+    // ── W11: You're all done (end-user final screen) ─────────────────
+    renderDone(container) {
+        container.style.cssText += "display:flex;flex-direction:column;align-items:center;text-align:center;gap:16px;padding:24px 0;";
+        container.setAttribute("role", "status");
+        // B7: Fire onComplete immediately when the done screen renders — the end
+        // user has completed their part regardless of whether they click Close.
+        // Firing here means the integrator always gets the event even if the user
+        // closes the modal via the ✕ button instead of the Close button.
+        this.options.onComplete?.({
+            entryId: this.livenessEntryId || 0,
+            sessionId: this.sdk.sessionToken,
+            status: "processing",
+            submittedAt: new Date().toISOString(),
+            verificationResult: this.verificationResult || undefined,
+        });
+        const iconWrap = document.createElement("div");
+        iconWrap.style.cssText = `width:80px;height:80px;border-radius:50%;background:${this.theme.successBg};border:3px solid ${this.theme.success};display:flex;align-items:center;justify-content:center;font-size:36px;font-weight:700;color:${this.theme.success};animation:sc-pop 0.4s ease;`;
+        iconWrap.textContent = "✓";
+        container.appendChild(iconWrap);
+        const title = document.createElement("h2");
+        title.style.cssText = `color:${this.theme.text};font-size:22px;font-weight:700;margin:0;`;
+        title.textContent = "You're all done!";
+        container.appendChild(title);
+        const brandName = this.sdkConfig?.brand_name || "the service";
+        const desc = document.createElement("p");
+        desc.style.cssText = `color:${this.theme.textSecondary};font-size:14px;line-height:1.6;margin:0;max-width:300px;`;
+        desc.textContent = `Your verification is complete. ${brandName} will review and be in touch shortly.`;
+        container.appendChild(desc);
+        // Subtle info line
+        const info = document.createElement("div");
+        info.style.cssText = `color:${this.theme.textMuted};font-size:11px;display:flex;align-items:center;gap:4px;`;
+        info.textContent = "🔒  Your data is encrypted and secure";
+        container.appendChild(info);
+        const doneBtn = this.createPrimaryButton("Close");
+        doneBtn.addEventListener("click", () => {
+            // onComplete already fired on render — just close the modal
+            this.close();
+        });
+        container.appendChild(doneBtn);
+    }
+    // ── W14: Retry limit reached ─────────────────────────────────────
+    _renderRetryLimitReached(container) {
+        container.style.cssText += "display:flex;flex-direction:column;align-items:center;text-align:center;gap:14px;padding:24px 0;";
+        const icon = document.createElement("div");
+        icon.style.cssText = `width:72px;height:72px;border-radius:50%;background:${this.theme.errorBg};border:3px solid ${this.theme.error};display:flex;align-items:center;justify-content:center;font-size:28px;`;
+        icon.textContent = "⚠️";
+        container.appendChild(icon);
+        const t = document.createElement("h2");
+        t.style.cssText = `color:${this.theme.text};font-size:18px;font-weight:700;margin:0;`;
+        t.textContent = "Unable to Complete Verification";
+        container.appendChild(t);
+        const d = document.createElement("p");
+        d.style.cssText = `color:${this.theme.textSecondary};font-size:13px;margin:0;max-width:280px;line-height:1.6;`;
+        d.textContent = "We were unable to complete your verification at this time. Please contact support or try again later.";
+        container.appendChild(d);
+        const closeBtn = this.createPrimaryButton("Close");
+        closeBtn.addEventListener("click", () => { this.options.onError?.(new Error("Retry limit reached")); this.close(); });
+        container.appendChild(closeBtn);
+    }
+    // ── W13: Camera pre-warm ─────────────────────────────────────────
+    _prewarmCamera() {
+        if (this._prewarmedStream || this.isDestroyed)
+            return;
+        navigator.mediaDevices?.getUserMedia?.({ video: { facingMode: "user" } })
+            .then(stream => {
+            if (this.isDestroyed) {
+                stream.getTracks().forEach(t => t.stop());
+                return;
+            }
+            this._prewarmedStream = stream;
+        })
+            .catch(() => { });
     }
     /**
      * Process document capture result with front/back support
      */
     async processDocumentCaptureResult(result, captureContainer, container) {
-        // Store both front and back blobs
-        this.documentBlob = result.front;
-        this.documentBackBlob = result.back || null;
-        // Process the front image through the existing flow
-        await this.processDocumentBlob(result.front, captureContainer, container);
-        // Log back image capture
-        if (result.back) {
-            console.log("Back image captured, size:", result.back.size);
-        }
+        // B2+P2: Compress both images once here. Do NOT assign documentBlob twice
+        // (old code set it to the raw blob first, then overwrote with compressed).
+        // processDocumentBlob also ran _compressImage — that second pass is removed
+        // below so compression only happens once.
+        this.documentBlob = await _compressImage(result.front, 1600, 0.85);
+        this.documentBackBlob = result.back ? await _compressImage(result.back, 1600, 0.85) : null;
+        // Process the front image — pass the already-compressed blob
+        await this.processDocumentBlob(this.documentBlob, captureContainer, container);
     }
     /**
      * Process document blob - common method for both CameraView and DocumentCapture
@@ -1032,7 +1562,7 @@ class SmartComplyFlow {
         let retryCount = 0;
         const attemptProcessing = async () => {
             try {
-                // Validate blob
+                // Validate blob — compression already done in processDocumentCaptureResult (P2)
                 if (!blob || blob.size === 0) {
                     throw new Error("Failed to capture document. Please try again.");
                 }
@@ -1045,13 +1575,20 @@ class SmartComplyFlow {
       <div style="display:flex;flex-direction:column;align-items:center;gap:14px;padding:28px 20px;">
         <div style="position:relative;width:52px;height:52px;">
           <div style="position:absolute;inset:0;border-radius:50%;border:3px solid ${this.theme.border};border-top-color:${this.theme.primary};animation:sc-spin 0.8s linear infinite;"></div>
-          <div style="position:absolute;inset:0;display:flex;align-items:center;justify-content:center;font-size:20px;">🔍</div>
+          <div style="position:absolute;inset:0;display:flex;align-items:center;justify-content:center;font-size:20px;">🔍</div>
         </div>
         <div style="color:${this.theme.text};font-size:14px;font-weight:600;">Scanning document...</div>
         <div style="color:${this.theme.textSecondary};font-size:12px;text-align:center;max-width:200px;line-height:1.5;">Running OCR and verifying your identity</div>
       </div>`;
-                // Create liveness entry with document
-                const identifier = `DOC-${Date.now()}`;
+                // Create liveness entry with document.
+                // Use the first collected field value as identifier when available
+                // (document flow has no data-verification step, so collectedFields is
+                // empty — fall back to the selected ID type code so the webhook
+                // subject.identifier is at least human-meaningful, not a raw timestamp).
+                const identifier = Object.values(this.collectedFields)[0]
+                    || this.idNumber
+                    || this.selectedIdType
+                    || `DOC-${Date.now()}`;
                 const COUNTRY_CODES = {
                     nigeria: "NG", ghana: "GH", kenya: "KE",
                     south_africa: "ZA", united_states: "US", united_kingdom: "GB", global: "US",
@@ -1095,10 +1632,9 @@ class SmartComplyFlow {
                     }
                 }
                 this.livenessEntryId = createResult.id;
-                // Document is already uploaded as part of liveness.create() above.
-                // Proceed straight to liveness — the backend runs OCR + face comparison
-                // after the liveness video is submitted, so there is no need to wait here.
-                this.showStep("liveness");
+                // W6: Route to OCR gate — poll until OCR result is ready, validate
+                // expiry/quality, then show document_confirm before liveness starts.
+                this.showStep("ocr_gate");
             }
             catch (err) {
                 console.error("Document processing failed:", err);
@@ -1111,7 +1647,7 @@ class SmartComplyFlow {
               <div style="display:flex;flex-direction:column;align-items:center;gap:16px;padding:28px 20px;text-align:center;">
                 <div style="position:relative;width:52px;height:52px;">
                   <div style="position:absolute;inset:0;border-radius:50%;border:3px solid ${this.theme.border};border-top-color:${this.theme.primary};animation:sc-spin 0.8s linear infinite;"></div>
-                  <div style="position:absolute;inset:0;display:flex;align-items:center;justify-content:center;font-size:20px;">🔄</div>
+                  <div style="position:absolute;inset:0;display:flex;align-items:center;justify-content:center;font-size:20px;">🔄</div>
                 </div>
                 <div style="color:${this.theme.text};font-size:14px;font-weight:600;">Retrying...</div>
                 <div style="color:${this.theme.textSecondary};font-size:12px;max-width:240px;line-height:1.5;">Attempt ${retryCount} of ${maxRetries}</div>
@@ -1130,55 +1666,65 @@ class SmartComplyFlow {
         await attemptProcessing();
     }
     handleDocumentProcessingError(error, captureContainer) {
-        let errorMessage = "Document verification failed. Please try again.";
+        // Map technical errors to user-friendly messages — never pass raw error strings
+        let userMessage = "We could not verify your document. Please try again.";
         let canRetry = true;
-        if (error.message) {
-            if (error.message.includes("expired")) {
-                errorMessage = "Document has expired. Please use a valid document.";
-                canRetry = false;
-            }
-            else if (error.message.includes("quality too low")) {
-                errorMessage = "Image quality too low. Please ensure the document is well-lit and clearly visible.";
-            }
-            else if (error.message.includes("Network") || error.message.includes("fetch")) {
-                errorMessage = "Network connection failed. Please check your internet connection and try again.";
-            }
-            else if (error.message.includes("413") || error.message.includes("too large")) {
-                errorMessage = "Document image is too large. Please use a smaller image or retake the photo.";
-            }
-            else if (error.message.includes("415") || error.message.includes("format")) {
-                errorMessage = "Unsupported image format. Please use JPEG or PNG images.";
-            }
+        const raw = (error?.message || "").toLowerCase();
+        if (raw.includes("expired")) {
+            userMessage = "The document you submitted has expired. Please use a valid, current ID.";
+            canRetry = false;
+        }
+        else if (raw.includes("quality too low") || raw.includes("blurry") || raw.includes("blur")) {
+            userMessage = "The document photo isn't clear enough. Please retake it in good lighting with no glare.";
+        }
+        else if (raw.includes("not detected") || raw.includes("document_not_detected")) {
+            userMessage = "We could not detect a document in the photo. Please ensure the full ID is visible and try again.";
+        }
+        else if (raw.includes("network") || raw.includes("fetch") || raw.includes("connection")) {
+            userMessage = "A connection error occurred. Please check your internet and try again.";
+        }
+        else if (raw.includes("too large") || raw.includes("413")) {
+            userMessage = "The document image is too large. Please retake the photo.";
+        }
+        else if (raw.includes("format") || raw.includes("415")) {
+            userMessage = "Unsupported image format. Please use JPEG or PNG.";
+        }
+        else if (raw.includes("type mismatch") || raw.includes("document_type_mismatch")) {
+            userMessage = "The document does not match the selected ID type. Please choose the correct ID type.";
         }
         if (captureContainer) {
-            captureContainer.innerHTML = `
-        <div style="display:flex;flex-direction:column;align-items:center;gap:16px;padding:28px 20px;text-align:center;">
-          <div style="width:56px;height:56px;border-radius:50%;background:${this.theme.errorBg || '#FEE'};border:3px solid ${this.theme.error || '#DC3545'};display:flex;align-items:center;justify-content:center;font-size:26px;">❌</div>
-          <div style="color:${this.theme.text};font-size:14px;font-weight:700;">Verification Failed</div>
-          <div style="color:${this.theme.textSecondary};font-size:13px;max-width:240px;line-height:1.6;">${errorMessage}</div>
-          ${canRetry ? `
-            <button id="retry-btn" style="
-              margin-top:8px;padding:12px 24px;border-radius:8px;
-              background:${this.theme.primary};color:white;
-              border:none;font-size:14px;font-weight:600;cursor:pointer;
-              transition:all 0.2s ease;
-            ">Try Again</button>
-          ` : ''}
-        </div>`;
+            // Build with DOM — never interpolate user-derived content into innerHTML
+            const wrap = document.createElement("div");
+            wrap.style.cssText = "display:flex;flex-direction:column;align-items:center;gap:16px;padding:28px 20px;text-align:center;";
+            wrap.setAttribute("role", "alert");
+            const icon = document.createElement("div");
+            icon.style.cssText = `width:56px;height:56px;border-radius:50%;background:${this.theme.errorBg};border:3px solid ${this.theme.error};display:flex;align-items:center;justify-content:center;font-size:26px;`;
+            icon.textContent = "🔍";
+            wrap.appendChild(icon);
+            const titleEl = document.createElement("div");
+            titleEl.style.cssText = `color:${this.theme.text};font-size:14px;font-weight:700;`;
+            titleEl.textContent = "Document Could Not Be Verified";
+            wrap.appendChild(titleEl);
+            const msgEl = document.createElement("div");
+            msgEl.style.cssText = `color:${this.theme.textSecondary};font-size:13px;max-width:260px;line-height:1.6;`;
+            msgEl.textContent = userMessage;
+            wrap.appendChild(msgEl);
             if (canRetry) {
-                const retryBtn = captureContainer.querySelector("#retry-btn");
-                if (retryBtn) {
-                    retryBtn.addEventListener("click", () => {
-                        this.showStep("document_capture");
-                    });
-                }
+                const retryBtn = document.createElement("button");
+                retryBtn.textContent = "Try Again";
+                retryBtn.setAttribute("aria-label", "Retake document photo");
+                retryBtn.style.cssText = `margin-top:8px;padding:12px 24px;border-radius:8px;background:${this.theme.primary};color:#fff;border:none;font-size:14px;font-weight:600;cursor:pointer;`;
+                retryBtn.addEventListener("click", () => this.showStep("document_capture"));
+                wrap.appendChild(retryBtn);
             }
+            captureContainer.innerHTML = "";
+            captureContainer.appendChild(wrap);
         }
         else {
-            this.showErrorStep(errorMessage);
+            this.showErrorStep(userMessage);
         }
     }
-    // ── Liveness ────────────────────────────────────────────────────
+    // ── Liveness ────────────────────────────────────────────────────
     renderLiveness(container) {
         container.style.cssText += "display:flex;flex-direction:column;gap:14px;";
         const title = this.createStepTitle("Face verification");
@@ -1191,15 +1737,14 @@ class SmartComplyFlow {
         const livenessContainer = document.createElement("div");
         livenessContainer.style.cssText = "margin:8px 0;width:100%;";
         container.appendChild(livenessContainer);
-        const identifier = this.idNumber || `DOC-${Date.now()}`;
+        // W10: For data verification, identifier is already held by the backend
+        // via identity_check_id — do not re-send it in liveness create.
+        const identifier = this.identityCheckId
+            ? "" // data verification — session holds context via identity_check_id
+            : (this.idNumber || Object.values(this.collectedFields)[0] || this.selectedIdType || `DOC-${Date.now()}`);
         const COUNTRY_CODES = {
-            nigeria: "NG",
-            ghana: "GH",
-            kenya: "KE",
-            south_africa: "ZA",
-            united_states: "US",
-            united_kingdom: "GB",
-            global: "US",
+            nigeria: "NG", ghana: "GH", kenya: "KE",
+            south_africa: "ZA", united_states: "US", united_kingdom: "GB", global: "US",
         };
         const country = COUNTRY_CODES[this.selectedCountry] || this.selectedCountry.toUpperCase().slice(0, 2);
         // Start liveness check (this handles camera, detection, recording, submission)
@@ -1212,237 +1757,86 @@ class SmartComplyFlow {
             document: this.documentBlob || undefined,
             document_back: this.documentBackBlob || undefined,
             identity_check: this.identityCheckId || undefined,
+            verification_type: this.identityCheckId
+                ? "data_verification"
+                : this.documentBlob
+                    ? "document_verification"
+                    : "liveness_only",
+            // B4: pass pre-warmed stream so camera.open() is skipped
+            prewarmedStream: this._prewarmedStream || undefined,
         }, ["BLINK", "TURN_HEAD", "OPEN_MOUTH"], this.livenessEntryId || undefined)
             .then((result) => {
-            this.showResult(result);
+            // W11: After submit, end user is done — show "You're all done" screen.
+            // Backend processing continues in background; client receives webhook.
+            // Track liveness failures for retry limit (W14).
+            if (result.status === "failed") {
+                this._livenessFailures++;
+            }
+            if (result.id) {
+                this.livenessEntryId = result.id;
+            }
+            this.showStep("done");
         })
             .catch((err) => {
+            this._livenessFailures++;
             this.showErrorStep(err.message || "Liveness verification failed. Please try again.");
         });
     }
-    // ── Result ──────────────────────────────────────────────────────
-    showResult(submitResult) {
-        this.currentStep = "result";
-        this.updateProgress();
-        if (!this.contentArea)
-            return;
-        this.contentArea.innerHTML = "";
-        const wrapper = document.createElement("div");
-        wrapper.style.cssText = `
-      display:flex;flex-direction:column;align-items:center;
-      text-align:center;gap:16px;padding:20px 0;
-      opacity:0;transform:scale(0.95);transition:all 0.4s ease;
-    `;
-        // Icon — starts as a spinner, updates when status resolves
-        const iconWrap = document.createElement("div");
-        iconWrap.style.cssText = `
-      width:80px;height:80px;border-radius:50%;
-      display:flex;align-items:center;justify-content:center;
-      font-size:36px;
-      background:${this.theme.cardBg};
-      border:3px solid ${this.theme.border};
-    `;
-        iconWrap.innerHTML = `<div style="width:32px;height:32px;border-radius:50%;border:3px solid ${this.theme.border};border-top-color:${this.theme.primary};animation:sc-spin 0.9s linear infinite;"></div>`;
-        wrapper.appendChild(iconWrap);
-        const title = document.createElement("h2");
-        title.style.cssText = `color:${this.theme.text};font-size:20px;font-weight:700;margin:0;`;
-        title.textContent = "Verification Submitted";
-        wrapper.appendChild(title);
-        const desc = document.createElement("p");
-        desc.style.cssText = `color:${this.theme.textSecondary};font-size:14px;line-height:1.6;margin:0;max-width:300px;`;
-        desc.textContent = "Processing your identity check. This takes around 30 seconds.";
-        wrapper.appendChild(desc);
-        // Details card
-        const details = document.createElement("div");
-        details.style.cssText = `
-      width:100%;padding:16px;border-radius:12px;
-      background:${this.theme.cardBg};border:1px solid ${this.theme.border};
-      text-align:left;
-    `;
-        // Status badge — mutable DOM node so polling can update it
-        const statusBadge = document.createElement("span");
-        statusBadge.style.cssText = `font-size:12px;font-weight:600;color:${this.theme.warning};`;
-        statusBadge.textContent = "Processing…";
-        const statusRow = document.createElement("div");
-        statusRow.style.cssText = "display:flex;justify-content:space-between;margin-bottom:8px;";
-        statusRow.innerHTML = `<span style="color:${this.theme.textMuted};font-size:12px;">Status</span>`;
-        statusRow.appendChild(statusBadge);
-        // Build rows via DOM (not innerHTML+=) to keep statusBadge live in the document
-        const entryRow = document.createElement("div");
-        entryRow.style.cssText = "display:flex;justify-content:space-between;margin-bottom:8px;";
-        entryRow.innerHTML = `
-      <span style="color:${this.theme.textMuted};font-size:12px;">Entry ID</span>
-      <span style="color:${this.theme.text};font-size:12px;font-weight:600;">${submitResult.id}</span>
-    `;
-        details.appendChild(entryRow);
-        details.appendChild(statusRow);
-        const submittedRow = document.createElement("div");
-        submittedRow.style.cssText = "display:flex;justify-content:space-between;margin-top:8px;";
-        submittedRow.innerHTML = `
-      <span style="color:${this.theme.textMuted};font-size:12px;">Submitted</span>
-      <span style="color:${this.theme.text};font-size:12px;">${submitResult.submitted_at ? new Date(submitResult.submitted_at).toLocaleString() : "Just now"}</span>
-    `;
-        details.appendChild(submittedRow);
-        wrapper.appendChild(details);
-        // Failure reason — hidden until status = failed
-        const failureMsg = document.createElement("div");
-        failureMsg.style.cssText = `
-      display:none;width:100%;padding:12px 14px;border-radius:10px;
-      background:${this.theme.errorBg};border:1px solid ${this.theme.error};
-      color:${this.theme.error};font-size:12px;text-align:left;line-height:1.5;
-    `;
-        wrapper.appendChild(failureMsg);
-        // Done button
-        const doneBtn = this.createPrimaryButton("Done");
-        let finalStatus = submitResult.status;
-        doneBtn.addEventListener("click", () => {
-            if (this._pollStatusTimer) {
-                clearTimeout(this._pollStatusTimer);
-                this._pollStatusTimer = null;
-            }
-            this.options.onComplete?.({
-                entryId: submitResult.id,
-                sessionId: this.sdk.sessionToken,
-                status: finalStatus,
-                submittedAt: submitResult.submitted_at,
-                verificationResult: this.verificationResult || undefined,
-            });
-            this.close();
-        });
-        wrapper.appendChild(doneBtn);
-        this.contentArea.appendChild(wrapper);
-        requestAnimationFrame(() => {
-            wrapper.style.opacity = "1";
-            wrapper.style.transform = "scale(1)";
-        });
-        // Start polling for the async result
-        this._startStatusPolling(submitResult.id, iconWrap, statusBadge, title, desc, failureMsg, (resolved) => { finalStatus = resolved; });
-    }
-    _startStatusPolling(entryId, iconWrap, statusBadge, title, desc, failureMsg, onResolved) {
-        const MAX_POLLS = 25; // 25 × 3 s = 75 s + 4 s initial = ~79 s max
-        let polls = 0;
-        // Hard 30 s UI timer — stops spinner even if backend is still processing
-        let uiTimeoutId = setTimeout(() => {
-            if (!this.isDestroyed)
-                applyTimeout();
-        }, 30000);
-        const clearUiTimeout = () => { if (uiTimeoutId) {
-            clearTimeout(uiTimeoutId);
-            uiTimeoutId = null;
-        } };
-        const applyTimeout = () => {
-            // Stop polling for real — the message below tells the user it's safe
-            // to close and that the result will arrive via webhook/dashboard.
-            // Silently continuing to poll in the background (up to another ~49s)
-            // used to mean the UI could suddenly flip to Verified/Failed after
-            // already telling the user to walk away, with no warning either way.
-            if (this._pollStatusTimer) {
-                clearTimeout(this._pollStatusTimer);
-                this._pollStatusTimer = null;
-            }
-            iconWrap.innerHTML = "⏱";
-            iconWrap.style.background = this.theme.cardBg;
-            iconWrap.style.border = `3px solid ${this.theme.warning}`;
-            iconWrap.style.color = this.theme.warning;
-            iconWrap.style.fontSize = "30px";
-            statusBadge.style.color = this.theme.textMuted;
-            statusBadge.textContent = "Still processing…";
-            title.textContent = "Verification In Progress";
-            desc.textContent = "Your verification is being processed. Your result will be delivered via your dashboard or webhook. You can safely close this.";
-        };
-        const applyPassed = () => {
-            clearUiTimeout();
-            iconWrap.innerHTML = "✓";
-            iconWrap.style.background = this.theme.successBg;
-            iconWrap.style.border = `3px solid ${this.theme.success}`;
-            iconWrap.style.color = this.theme.success;
-            iconWrap.style.fontSize = "36px";
-            statusBadge.style.color = this.theme.success;
-            statusBadge.textContent = "Verified ✓";
-            title.textContent = "Identity Verified";
-            desc.textContent = "Your identity check passed successfully.";
-        };
-        const applyFailed = (reason) => {
-            clearUiTimeout();
-            iconWrap.innerHTML = "✕";
-            iconWrap.style.background = this.theme.errorBg;
-            iconWrap.style.border = `3px solid ${this.theme.error}`;
-            iconWrap.style.color = this.theme.error;
-            iconWrap.style.fontSize = "32px";
-            statusBadge.style.color = this.theme.error;
-            statusBadge.textContent = "Failed";
-            title.textContent = "Verification Failed";
-            desc.textContent = "Your identity check could not be completed.";
-            if (reason) {
-                failureMsg.textContent = reason;
-                failureMsg.style.display = "block";
-            }
-        };
-        const poll = async () => {
-            if (this.isDestroyed)
-                return;
-            polls++;
-            try {
-                const result = await this.sdk.liveness.pollResult(entryId);
-                if (result.status === "passed") {
-                    onResolved("passed");
-                    applyPassed();
-                    return;
-                }
-                if (result.status === "failed") {
-                    onResolved(result.status);
-                    const reason = result.failure_reason || "Verification could not be completed. Please try again.";
-                    applyFailed(reason);
-                    return;
-                }
-                // Still pending/processing — schedule next poll if budget remains
-                if (polls < MAX_POLLS && !this.isDestroyed) {
-                    this._pollStatusTimer = setTimeout(poll, 3000);
-                }
-                else if (!this.isDestroyed) {
-                    applyTimeout(); // budget exhausted — stop spinner, show timeout state
-                }
-            }
-            catch {
-                // Network hiccup — retry with a slightly longer delay
-                if (polls < MAX_POLLS && !this.isDestroyed) {
-                    this._pollStatusTimer = setTimeout(poll, 5000);
-                }
-                else if (!this.isDestroyed) {
-                    applyTimeout(); // budget exhausted — stop spinner
-                }
-            }
-        };
-        // First poll after 4 s — gives Celery task time to complete
-        this._pollStatusTimer = setTimeout(poll, 4000);
-    }
     renderResult(_container) {
-        // Handled by showResult() directly
+        // C2: Dead code — flow routes to 'done' step, not 'result'. Kept as stub.
     }
-    // ── Error ───────────────────────────────────────────────────────
+    // ── Error ───────────────────────────────────────────────────────
     showErrorStep(message) {
         this.currentStep = "error";
         if (!this.contentArea)
             return;
         this.contentArea.innerHTML = "";
         const wrapper = document.createElement("div");
+        wrapper.setAttribute("role", "alert");
         wrapper.style.cssText = `
       display:flex;flex-direction:column;align-items:center;
       text-align:center;gap:16px;padding:20px 0;
     `;
+        // Classify the error into a user-friendly category
         const isCameraErr = /camera|permission|notallowed|notfound/i.test(message);
         const isNetworkErr = /network|timeout|connection|fetch/i.test(message);
-        const isAuthErr = /session|token|expired|authentication/i.test(message);
-        const errorIcon = isCameraErr ? "\uD83D\uDCF7" : isNetworkErr ? "\uD83D\uDCE1" : isAuthErr ? "\u23F1" : "\u2717";
+        const isAuthErr = /session.*expired|token.*expired|authentication/i.test(message);
+        const isDocQuality = /blurry|blur|quality|glare|dark|bright|lighting/i.test(message);
+        const isExpiredDoc = /document.*expired|expired.*document/i.test(message);
+        const isFaceMatch = /face.*match|selfie.*match|does not match/i.test(message);
+        const errorIcon = isCameraErr ? "📷"
+            : isNetworkErr ? "📡"
+                : isAuthErr ? "⏱"
+                    : isDocQuality ? "🔍"
+                        : isExpiredDoc ? "📅"
+                            : isFaceMatch ? "🤳"
+                                : "✕";
         const errorTitle = isCameraErr ? "Camera Access Required"
             : isNetworkErr ? "Connection Problem"
                 : isAuthErr ? "Session Expired"
-                    : "Verification Failed";
+                    : isDocQuality ? "Document Photo Unclear"
+                        : isExpiredDoc ? "Document Expired"
+                            : isFaceMatch ? "Face Match Failed"
+                                : "Verification Unsuccessful";
+        // Map to user-facing guidance — never show raw internal message
+        const userMessage = isCameraErr
+            ? "Please allow camera access in your browser settings and try again."
+            : isNetworkErr
+                ? "Check your internet connection and try again."
+                : isAuthErr
+                    ? "Your session has expired. Please start again."
+                    : isDocQuality
+                        ? _sanitizeUserMessage(message) || "Please retake your document photo in good lighting with no glare."
+                        : isExpiredDoc
+                            ? "The document you submitted has expired. Please use a valid, current ID."
+                            : isFaceMatch
+                                ? "Your selfie did not match the photo on your ID. Please ensure you are using your own valid document and face the camera directly."
+                                : _sanitizeUserMessage(message) || "We were unable to complete your verification. Please try again.";
         const iconWrap = document.createElement("div");
         iconWrap.style.cssText = `
       width:72px;height:72px;border-radius:50%;
       display:flex;align-items:center;justify-content:center;
-      font-size:${errorIcon === "\u2717" ? "32px" : "28px"};
+      font-size:28px;
       background:${this.theme.errorBg};
       border:3px solid ${this.theme.error};
     `;
@@ -1454,22 +1848,16 @@ class SmartComplyFlow {
         wrapper.appendChild(title);
         const desc = document.createElement("p");
         desc.style.cssText = `color:${this.theme.textSecondary};font-size:14px;line-height:1.6;margin:0;max-width:300px;`;
-        desc.textContent = message;
+        desc.textContent = userMessage;
         wrapper.appendChild(desc);
         const retryBtn = this.createPrimaryButton("Try Again");
+        retryBtn.setAttribute("aria-label", "Try verification again");
         retryBtn.addEventListener("click", () => {
-            // If session already exists, go back to welcome without re-initializing
-            // (re-initializing would fail with CLIENT_ID_ALREADY_USED)
-            if (this.sdk.sessionToken && this.sdkConfig) {
-                this.showStep("welcome");
-            }
-            else {
-                // Only re-initialize if session was never created
-                this.initialize();
-            }
+            this.initialize();
         });
         wrapper.appendChild(retryBtn);
         const closeBtn = this.createSecondaryButton("Close");
+        closeBtn.setAttribute("aria-label", "Close verification widget");
         closeBtn.addEventListener("click", () => {
             this.options.onError?.(new Error(message));
             this.close();
@@ -1477,11 +1865,12 @@ class SmartComplyFlow {
         wrapper.appendChild(closeBtn);
         this.contentArea.appendChild(wrapper);
     }
-    // ─────────────────────────────────────────────────────────────────
+    // ─────────────────────────────────────────────────────────────────
     // UI Helpers
-    // ─────────────────────────────────────────────────────────────────
+    // ─────────────────────────────────────────────────────────────────
     createHeader() {
         const header = document.createElement("div");
+        header.setAttribute("role", "banner");
         header.style.cssText = `
       display:flex;align-items:center;justify-content:space-between;
       padding:11px 20px;border-bottom:1px solid ${this.theme.border};
@@ -1491,6 +1880,7 @@ class SmartComplyFlow {
         leftArea.style.cssText = "display:flex;align-items:center;gap:8px;min-width:0;";
         this.headerBackBtn = document.createElement("button");
         this.headerBackBtn.innerHTML = "&#8592;";
+        this.headerBackBtn.setAttribute("aria-label", "Go back to previous step");
         this.headerBackBtn.style.cssText = `
       width:30px;height:30px;border-radius:8px;flex-shrink:0;
       display:none;align-items:center;justify-content:center;
@@ -1499,6 +1889,7 @@ class SmartComplyFlow {
       background:${this.theme.cardBg};color:${this.theme.text};
       transition:all 0.2s ease;
     `;
+        this.headerBackBtn.style.cssText += `:focus-visible{outline:2px solid ${this.theme.primary};outline-offset:2px;}`;
         this.headerBackBtn.addEventListener("mouseenter", () => {
             if (this.headerBackBtn) {
                 this.headerBackBtn.style.background = this.theme.shimmer;
@@ -1511,6 +1902,7 @@ class SmartComplyFlow {
         });
         leftArea.appendChild(this.headerBackBtn);
         this.brandLabel = document.createElement("div");
+        this.brandLabel.setAttribute("aria-label", "Verification provider");
         this.brandLabel.style.cssText = `
       font-size:15px;font-weight:700;color:${this.theme.text};
       white-space:nowrap;overflow:hidden;text-overflow:ellipsis;
@@ -1520,6 +1912,8 @@ class SmartComplyFlow {
         header.appendChild(leftArea);
         // Step indicator
         this.stepLabel = document.createElement("div");
+        this.stepLabel.setAttribute("aria-live", "polite");
+        this.stepLabel.setAttribute("aria-atomic", "true");
         this.stepLabel.style.cssText = `
       font-size:12px;color:${this.theme.textMuted};
       font-variant-numeric:tabular-nums;flex-shrink:0;
@@ -1527,7 +1921,8 @@ class SmartComplyFlow {
         header.appendChild(this.stepLabel);
         // Close button
         const closeBtn = document.createElement("button");
-        closeBtn.innerHTML = "✕";
+        closeBtn.innerHTML = "✕";
+        closeBtn.setAttribute("aria-label", "Close identity verification");
         closeBtn.style.cssText = `
       width:32px;height:32px;border-radius:8px;flex-shrink:0;
       display:flex;align-items:center;justify-content:center;
@@ -1574,6 +1969,7 @@ class SmartComplyFlow {
     }
     createOptionCard(title, subtitle, onClick) {
         const card = document.createElement("button");
+        card.setAttribute("aria-label", subtitle ? `${title}: ${subtitle}` : title);
         card.style.cssText = `
       width:100%;padding:13px 16px;border-radius:12px;
       background:${this.theme.cardBg};
@@ -1606,7 +2002,7 @@ class SmartComplyFlow {
         }
         const arrow = document.createElement("span");
         arrow.style.cssText = `color:${this.theme.textMuted};font-size:18px;flex-shrink:0;`;
-        arrow.textContent = "→";
+        arrow.textContent = "→";
         card.appendChild(textWrap);
         card.appendChild(arrow);
         return card;
@@ -1651,7 +2047,7 @@ class SmartComplyFlow {
         return btn;
     }
     isDocumentFlow() {
-        // 1. Check verification_type — handle both string and array from backend
+        // 1. Check verification_type — handle both string and array from backend
         const vType = this.sdkConfig?.verification_type;
         if (vType) {
             const types = Array.isArray(vType) ? vType : [vType];
@@ -1660,7 +2056,7 @@ class SmartComplyFlow {
             if (types.includes("data_verification"))
                 return false;
         }
-        // 2. Fallback: inspect channel fields — any upload field = document flow
+        // 2. Fallback: inspect channel fields — any upload field = document flow
         const channels = this.sdkConfig?.channels || {};
         const allFields = Object.values(channels)
             .flat()
@@ -1671,38 +2067,47 @@ class SmartComplyFlow {
         const isDocFlow = this.isDocumentFlow();
         const countries = Object.keys(this.sdkConfig?.channels || {});
         const singleCountry = countries.length <= 1;
-        // User-action steps only (what the user actually does — no loading/welcome/result)
-        const actionSteps = ["country", "id_type", isDocFlow ? "document_capture" : "id_input", "liveness"].filter((s) => !(s === "country" && singleCountry));
-        const totalSteps = actionSteps.length;
-        const actionIndex = actionSteps.indexOf(this.currentStep);
-        const pct = this.currentStep === "result" ? 100
+        // Two-stage action steps — Stage 1: validate identity, Stage 2: liveness
+        const stage1Steps = isDocFlow
+            ? ["country", "id_type", "document_capture", "ocr_gate", "document_confirm"].filter(s => !(s === "country" && singleCountry))
+            : ["country", "id_type", "id_input", "confirm_identity"].filter(s => !(s === "country" && singleCountry));
+        const stage2Steps = ["liveness"];
+        const allActionSteps = [...stage1Steps, ...stage2Steps];
+        const totalSteps = allActionSteps.length;
+        const actionIndex = allActionSteps.indexOf(this.currentStep);
+        const pct = this.currentStep === "done" || this.currentStep === "result" ? 100
             : actionIndex >= 0 ? ((actionIndex + 1) / totalSteps) * 100
                 : 0;
         if (this.progressBar) {
             this.progressBar.style.width = `${pct}%`;
         }
+        // Stage label: "Stage 1 of 2: Verify Identity" / "Stage 2 of 2: Face Check"
         if (this.stepLabel) {
             if (this.currentStep === "loading" || this.currentStep === "welcome") {
                 this.stepLabel.textContent = "";
             }
-            else if (this.currentStep === "result") {
-                this.stepLabel.textContent = "Complete ✓";
+            else if (this.currentStep === "done" || this.currentStep === "result") {
+                this.stepLabel.textContent = "Complete ✓";
+            }
+            else if (stage2Steps.includes(this.currentStep)) {
+                this.stepLabel.textContent = "Stage 2 of 2: Face Check";
             }
-            else if (actionIndex >= 0) {
-                this.stepLabel.textContent = `Step ${actionIndex + 1} of ${totalSteps}`;
+            else if (stage1Steps.includes(this.currentStep)) {
+                this.stepLabel.textContent = isDocFlow ? "Stage 1 of 2: Scan Document" : "Stage 1 of 2: Verify Identity";
             }
             else {
                 this.stepLabel.textContent = "";
             }
         }
-        // Back button — show in header for navigable steps, hidden elsewhere
+        // Back button — show for navigable steps only
         if (this.headerBackBtn) {
-            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"); },
             };
             const backAction = backTargets[this.currentStep];
             if (backAction) {
@@ -1752,6 +2157,12 @@ class SmartComplyFlow {
       #sc-flow-modal * {
         box-sizing: border-box;
       }
+      #sc-flow-modal button:focus-visible,
+      #sc-flow-modal select:focus-visible,
+      #sc-flow-modal input:focus-visible {
+        outline: 2px solid #3b82f6;
+        outline-offset: 2px;
+      }
       #sc-flow-modal::-webkit-scrollbar {
         width: 4px;
       }
@@ -1767,4 +2178,5 @@ class SmartComplyFlow {
     }
 }
 exports.SmartComplyFlow = SmartComplyFlow;
+SmartComplyFlow.MAX_RETRIES = 3;
 //# sourceMappingURL=SmartComplyFlow.js.map