smartcomply-web-sdk 1.0.42 → 1.0.45

package/dist/esm/flow/SmartComplyFlow.js

@@ -22,6 +22,13 @@ const COUNTRY_LABELS = {
     united_states: "🇺🇸  United States",
     united_kingdom: "🇬🇧  United Kingdom",
 };
+// 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.
+function isUploadFieldType(type) {
+    return type === "upload" || type === "image" || type === "file";
+}
 function resolveIdTypeInfo(typeName, isDocumentFlow) {
     const u = typeName.toUpperCase();
     const advanced = u.includes("ADVANCED");
@@ -116,6 +123,55 @@ function resolveIdTypeInfo(typeName, isDocumentFlow) {
     };
 }
 // ─────────────────────────────────────────────────────────────────────
+// ── 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();
+}
+// ── 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
@@ -164,6 +220,7 @@ export class SmartComplyFlow {
         this._pollStatusTimer = null;
         // Components
         this.docCapture = null;
+        this._livenessSubmitResult = null;
         this.options = options;
         this.sdk = new SmartComply({
             apiKey: options.apiKey,
@@ -239,6 +296,9 @@ export 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};
@@ -264,6 +324,9 @@ export 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;
@@ -365,7 +428,7 @@ export class SmartComplyFlow {
                 this.renderDocumentCapture(wrapper);
                 break;
             case "processing":
-                this.renderProcessing(wrapper);
+                this.renderProcessing(wrapper, this.livenessEntryId || undefined);
                 break;
             case "liveness":
                 this.renderLiveness(wrapper);
@@ -573,7 +636,7 @@ export class SmartComplyFlow {
             const typeCode = typeof idType === "string" ? idType : (idType.code || idType.name);
             // Detect per-channel: does THIS specific channel have upload fields?
             const channelFields = typeof idType !== "string" ? (idType.fields || []) : [];
-            const isThisDocFlow = channelFields.some((f) => f.type === "upload") || globalDocFlow;
+            const isThisDocFlow = channelFields.some((f) => isUploadFieldType(f.type)) || globalDocFlow;
             const info = resolveIdTypeInfo(typeName, isThisDocFlow);
             // Prefer the backend-provided back-side flag; fall back to local heuristics only when absent.
             const requiresBackFromBackend = typeof idType !== "string" ? idType.requires_back_side : undefined;
@@ -611,7 +674,7 @@ export class SmartComplyFlow {
                 }
                 // Route: use explicit verification_type when set (more reliable than inspecting all channels)
                 // Fallback to per-channel upload field check for mixed / unconfigured setups
-                const hasUpload = (this.selectedChannelFields).some((f) => f.type === "upload");
+                const hasUpload = (this.selectedChannelFields).some((f) => isUploadFieldType(f.type));
                 const vType = this.sdkConfig?.verification_type;
                 const vTypes = vType ? (Array.isArray(vType) ? vType : [vType]) : [];
                 const isDocChannel = hasUpload || (vTypes.length > 0 && vTypes.includes("document_verification"));
@@ -654,6 +717,41 @@ export 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) {
@@ -666,7 +764,10 @@ export 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);
@@ -740,10 +841,18 @@ export 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;
@@ -754,17 +863,50 @@ export 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);
@@ -782,9 +924,16 @@ export 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;
@@ -804,7 +953,7 @@ export class SmartComplyFlow {
                     this.showStep("liveness");
                 }
                 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;
@@ -812,14 +961,26 @@ export 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";
@@ -875,130 +1036,140 @@ export 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);
+    // ── Processing (real polling-driven, document flow only) ────────────
+    renderProcessing(container, entryId) {
+        container.style.cssText += "display:flex;flex-direction:column;align-items:center;gap:16px;padding:16px;";
+        // Spinner
+        const spinnerWrap = document.createElement("div");
+        spinnerWrap.style.cssText = "position:relative;width:56px;height:56px;flex-shrink:0;";
+        const ring = document.createElement("div");
+        ring.id = "sc-proc-ring";
+        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 centerIcon = document.createElement("div");
-        centerIcon.style.cssText = `
-      position:absolute;inset:0;display:flex;align-items:center;justify-content:center;
-      font-size:20px;
-    `;
+        centerIcon.style.cssText = "position:absolute;inset:0;display:flex;align-items:center;justify-content:center;font-size:22px;";
         centerIcon.textContent = "🔍";
-        animationWrap.appendChild(centerIcon);
-        container.appendChild(animationWrap);
+        spinnerWrap.appendChild(ring);
+        spinnerWrap.appendChild(centerIcon);
+        container.appendChild(spinnerWrap);
         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";
+        title.textContent = "Verifying your document";
         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: '🔬' },
+        // Live status line — updated by polling
+        const statusLine = document.createElement("div");
+        statusLine.id = "sc-proc-status";
+        statusLine.setAttribute("aria-live", "polite");
+        statusLine.setAttribute("aria-atomic", "true");
+        statusLine.style.cssText = `color:${this.theme.textSecondary};font-size:12px;text-align:center;max-width:260px;line-height:1.5;`;
+        statusLine.textContent = "Scanning document…";
+        container.appendChild(statusLine);
+        // Step checklist — reflects real pipeline stages
+        const stages = [
+            { id: "ocr", label: "Reading document", icon: "📄" },
+            { id: "expiry", label: "Checking expiry", icon: "📅" },
+            { id: "face", label: "Face match", icon: "🤳" },
+            { id: "result", label: "Finalising result", 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;
+        const grid = document.createElement("div");
+        grid.style.cssText = "width:100%;display:grid;grid-template-columns:1fr 1fr;gap:8px;";
+        stages.forEach((s) => {
+            const el = document.createElement("div");
+            el.id = `sc-stage-${s.id}`;
+            el.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;`;
+            el.innerHTML = `
+        <div style="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};">${s.icon}</div>
+        <div style="flex:1;color:${this.theme.textSecondary};font-size:11px;font-weight:500;">${s.label}</div>
+        <div id="sc-stage-status-${s.id}" style="width:14px;height:14px;border-radius:50%;border:2px solid ${this.theme.border};flex-shrink:0;"></div>
       `;
-            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);
+            grid.appendChild(el);
         });
-        container.appendChild(stepsContainer);
-        this.startProcessingAnimation();
+        container.appendChild(grid);
+        // Start polling immediately — update stages as result comes in
+        if (entryId) {
+            this._pollProcessingStages(entryId, statusLine, grid, stages);
+        }
     }
-    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>
-        `;
-            }
-            // Move to next step after delay
+    _pollProcessingStages(entryId, statusLine, _grid, stages) {
+        // Animate stages sequentially on a timer — OCR takes ~5–15s,
+        // face match another ~5–15s. We can't observe sub-steps from the
+        // public sdk-result endpoint, so we advance stages on elapsed time
+        // AND on the final status transition.
+        const stageTimings = [0, 4000, 10000, 18000]; // ms after poll start
+        const startTime = Date.now();
+        const setStageActive = (stageId) => {
+            const el = document.getElementById(`sc-stage-${stageId}`);
+            const statusEl = document.getElementById(`sc-stage-status-${stageId}`);
+            if (!el || !statusEl)
+                return;
+            el.style.borderColor = this.theme.primary;
+            el.style.background = `${this.theme.primary}10`;
+            statusEl.innerHTML = `<div style="position:absolute;inset:1px;border-radius:50%;border:2px solid ${this.theme.border};border-top-color:${this.theme.primary};animation:sc-spin 0.8s linear infinite;"></div>`;
+            statusEl.style.position = "relative";
+        };
+        const setStageComplete = (stageId) => {
+            const el = document.getElementById(`sc-stage-${stageId}`);
+            const statusEl = document.getElementById(`sc-stage-status-${stageId}`);
+            if (!el || !statusEl)
+                return;
+            el.style.borderColor = this.theme.success || "#22c55e";
+            el.style.background = `${this.theme.success || "#22c55e"}10`;
+            statusEl.innerHTML = `<div style="position:absolute;inset:2px;border-radius:50%;background:${this.theme.success || "#22c55e"};display:flex;align-items:center;justify-content:center;color:#fff;font-size:8px;font-weight:bold;">✓</div>`;
+            statusEl.style.position = "relative";
+        };
+        // Advance stage indicators on timer
+        stages.forEach((s, i) => {
             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>
-          `;
-                }
-                currentStepIndex++;
-                if (currentStepIndex < steps.length) {
-                    animateStep(steps[currentStepIndex]);
+                if (this.isDestroyed)
+                    return;
+                setStageActive(s.id);
+                if (i > 0)
+                    setStageComplete(stages[i - 1].id);
+                statusLine.textContent = s.id === "ocr"
+                    ? "Scanning document…"
+                    : s.id === "expiry"
+                        ? "Checking expiry date…"
+                        : s.id === "face"
+                            ? "Running face match…"
+                            : "Finalising result…";
+            }, stageTimings[i]);
+        });
+        // Poll for real result
+        const MAX_POLLS = 30; // 30 × 3s = 90s max
+        let polls = 0;
+        const poll = async () => {
+            if (this.isDestroyed)
+                return;
+            polls++;
+            try {
+                const result = await this.sdk.liveness.pollResult(entryId);
+                if (result.status === "passed" || result.status === "failed") {
+                    // Mark all remaining stages complete
+                    stages.forEach((s) => setStageComplete(s.id));
+                    statusLine.textContent = result.status === "passed"
+                        ? "Verification complete ✓"
+                        : "Verification finished";
+                    // Short delay so user sees the completed states, then show result
+                    setTimeout(() => {
+                        if (!this.isDestroyed) {
+                            this._livenessSubmitResult = result;
+                            this.showResult(result);
+                        }
+                    }, 800);
+                    return;
                 }
-            }, 2000); // 2 seconds per step
+            }
+            catch { /* network hiccup — keep polling */ }
+            if (polls < MAX_POLLS && !this.isDestroyed) {
+                this._pollStatusTimer = setTimeout(poll, 3000);
+            }
+            else if (!this.isDestroyed) {
+                // Timeout — transition to result screen with current status
+                stages.forEach((s) => setStageComplete(s.id));
+                statusLine.textContent = "Still processing — check back soon";
+            }
         };
-        // Start animation
-        setTimeout(() => animateStep(steps[0]), 500);
+        // First poll after 5s — give Celery task time to start
+        this._pollStatusTimer = setTimeout(poll, 5000);
     }
     /**
      * Process document capture result with front/back support
@@ -1040,8 +1211,15 @@ export class SmartComplyFlow {
         <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",
@@ -1120,52 +1298,62 @@ export 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 ────────────────────────────────────────────────────
@@ -1181,7 +1369,10 @@ export 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()}`;
+        const identifier = this.idNumber
+            || Object.values(this.collectedFields)[0]
+            || this.selectedIdType
+            || `DOC-${Date.now()}`;
         const COUNTRY_CODES = {
             nigeria: "NG",
             ghana: "GH",
@@ -1202,9 +1393,25 @@ export class SmartComplyFlow {
             document: this.documentBlob || undefined,
             document_back: this.documentBackBlob || undefined,
             identity_check: this.identityCheckId || undefined,
+            // Tell the module which flow we're in so it can skip video for data verification
+            verification_type: this.identityCheckId
+                ? "data_verification"
+                : this.documentBlob
+                    ? "document_verification"
+                    : "liveness_only",
         }, ["BLINK", "TURN_HEAD", "OPEN_MOUTH"], this.livenessEntryId || undefined)
             .then((result) => {
-            this.showResult(result);
+            // For document/data verification the backend processes async.
+            // Route through the processing step so the user sees real pipeline
+            // progress instead of jumping straight to result.
+            const isAsync = !!(this.documentBlob || this.identityCheckId);
+            if (isAsync && result.id) {
+                this.livenessEntryId = result.id;
+                this.showStep("processing");
+            }
+            else {
+                this.showResult(result);
+            }
         })
             .catch((err) => {
             this.showErrorStep(err.message || "Liveness verification failed. Please try again.");
@@ -1218,12 +1425,14 @@ export class SmartComplyFlow {
             return;
         this.contentArea.innerHTML = "";
         const wrapper = document.createElement("div");
+        wrapper.setAttribute("role", "region");
+        wrapper.setAttribute("aria-label", "Verification result");
         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
+        // ── Icon — spinner until status resolves ────────────────────────
         const iconWrap = document.createElement("div");
         iconWrap.style.cssText = `
       width:80px;height:80px;border-radius:50%;
@@ -1231,59 +1440,68 @@ export class SmartComplyFlow {
       font-size:36px;
       background:${this.theme.cardBg};
       border:3px solid ${this.theme.border};
+      transition:all 0.4s ease;
     `;
         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);
+        // ── Title and description — updated by polling ───────────────────
         const title = document.createElement("h2");
+        title.setAttribute("aria-live", "polite");
         title.style.cssText = `color:${this.theme.text};font-size:20px;font-weight:700;margin:0;`;
-        title.textContent = "Verification Submitted";
+        title.textContent = "Checking your identity…";
         wrapper.appendChild(title);
         const desc = document.createElement("p");
+        desc.setAttribute("aria-live", "polite");
         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.";
+        desc.textContent = "This usually takes a few seconds. Please wait.";
         wrapper.appendChild(desc);
-        // Details card
-        const details = document.createElement("div");
-        details.style.cssText = `
+        // ── Result card — initially shows status only ────────────────────
+        // Populated with name/doc type when verification completes.
+        const resultCard = document.createElement("div");
+        resultCard.style.cssText = `
       width:100%;padding:16px;border-radius:12px;
       background:${this.theme.cardBg};border:1px solid ${this.theme.border};
-      text-align:left;
+      text-align:left;display:flex;flex-direction:column;gap:10px;
+      transition:border-color 0.3s ease;
     `;
-        // Status badge — mutable DOM node so polling can update it
+        // Status row — always shown
         const statusBadge = document.createElement("span");
+        statusBadge.setAttribute("role", "status");
+        statusBadge.setAttribute("aria-live", "polite");
+        statusBadge.setAttribute("aria-atomic", "true");
         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.style.cssText = "display:flex;justify-content:space-between;align-items:center;";
+        statusRow.innerHTML = `<span style="color:${this.theme.textMuted};font-size:12px;font-weight:500;">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
+        resultCard.appendChild(statusRow);
+        // Verified details — shown only when passed.
+        // nameRow: shows full name from IVS result or OCR
+        // docTypeRow: shows document type verified
+        const nameRow = document.createElement("div");
+        nameRow.style.cssText = "display:none;justify-content:space-between;align-items:center;";
+        nameRow.innerHTML = `<span style="color:${this.theme.textMuted};font-size:12px;font-weight:500;">Name</span><span id="sc-result-name" style="color:${this.theme.text};font-size:12px;font-weight:600;text-align:right;max-width:60%;"></span>`;
+        resultCard.appendChild(nameRow);
+        const docTypeRow = document.createElement("div");
+        docTypeRow.style.cssText = "display:none;justify-content:space-between;align-items:center;";
+        docTypeRow.innerHTML = `<span style="color:${this.theme.textMuted};font-size:12px;font-weight:500;">ID Type</span><span id="sc-result-doctype" style="color:${this.theme.text};font-size:12px;font-weight:600;"></span>`;
+        resultCard.appendChild(docTypeRow);
+        wrapper.appendChild(resultCard);
+        // ── Failure reason — shown only when failed ──────────────────────
         const failureMsg = document.createElement("div");
+        failureMsg.setAttribute("role", "alert");
         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;
+      color:${this.theme.error};font-size:13px;text-align:left;line-height:1.6;
     `;
         wrapper.appendChild(failureMsg);
-        // Done button
+        // ── Action buttons ───────────────────────────────────────────────
+        const btnRow = document.createElement("div");
+        btnRow.style.cssText = "display:flex;flex-direction:column;gap:8px;width:100%;";
         const doneBtn = this.createPrimaryButton("Done");
+        doneBtn.setAttribute("aria-label", "Close verification and continue");
         let finalStatus = submitResult.status;
         doneBtn.addEventListener("click", () => {
             if (this._pollStatusTimer) {
@@ -1299,74 +1517,107 @@ export class SmartComplyFlow {
             });
             this.close();
         });
-        wrapper.appendChild(doneBtn);
+        btnRow.appendChild(doneBtn);
+        // "Try again" button — shown only on failure, hidden initially
+        const retryBtn = this.createSecondaryButton("Try Again");
+        retryBtn.setAttribute("aria-label", "Start verification again");
+        retryBtn.style.display = "none";
+        retryBtn.addEventListener("click", () => {
+            if (this._pollStatusTimer) {
+                clearTimeout(this._pollStatusTimer);
+                this._pollStatusTimer = null;
+            }
+            this.initialize();
+        });
+        btnRow.appendChild(retryBtn);
+        wrapper.appendChild(btnRow);
         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; });
+        // ── Start polling ────────────────────────────────────────────────
+        this._startStatusPolling(submitResult.id, iconWrap, statusBadge, title, desc, resultCard, nameRow, docTypeRow, failureMsg, retryBtn, (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
+    _startStatusPolling(entryId, iconWrap, statusBadge, title, desc, resultCard, nameRow, docTypeRow, failureMsg, retryBtn, onResolved) {
+        const MAX_POLLS = 25; // 25 × 3s = 75s + 4s initial ≈ 79s max
         let polls = 0;
-        // Hard 30 s UI timer — stops spinner even if backend is still processing
+        // Hard 30s UI timer — stop spinner and tell user to wait even if backend is slower
         let uiTimeoutId = setTimeout(() => {
             if (!this.isDestroyed)
                 applyTimeout();
         }, 30000);
-        const clearUiTimeout = () => { if (uiTimeoutId) {
-            clearTimeout(uiTimeoutId);
-            uiTimeoutId = null;
-        } };
+        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.innerHTML = "⏳";
             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.";
+            title.textContent = "Still verifying";
+            desc.textContent = "This is taking a little longer than usual. You can safely close this — your result will be available in your account.";
         };
-        const applyPassed = () => {
+        const applyPassed = (result) => {
             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";
+            iconWrap.style.cssText += `background:${this.theme.successBg};border:3px solid ${this.theme.success};color:${this.theme.success};font-size:36px;font-weight:700;`;
+            resultCard.style.borderColor = this.theme.success;
             statusBadge.style.color = this.theme.success;
             statusBadge.textContent = "Verified ✓";
             title.textContent = "Identity Verified";
-            desc.textContent = "Your identity check passed successfully.";
+            desc.textContent = "Your identity has been confirmed successfully.";
+            // ── Show name if available ───────────────────────────────────────
+            // Pull from IVS customer_profile (data verification) or
+            // document OCR result (document verification) — whichever has data.
+            const profile = result?.customer_profile || result?.data || {};
+            const docResult = result?.document || {};
+            const ocr = docResult?.ocr_result || {};
+            const firstName = (profile?.first_name || ocr?.first_name || docResult?.first_name || "").trim();
+            const lastName = (profile?.last_name || profile?.surname ||
+                ocr?.last_name || ocr?.surname || docResult?.last_name || "").trim();
+            const fullName = [firstName, lastName].filter(Boolean).join(" ");
+            const nameEl = document.getElementById("sc-result-name");
+            if (fullName && nameEl) {
+                nameEl.textContent = fullName;
+                nameRow.style.display = "flex";
+            }
+            // ── Show ID type ─────────────────────────────────────────────────
+            const rawDocType = (docResult?.document_type ||
+                this.selectedIdType ||
+                result?.identifier_type ||
+                "");
+            const docTypeLabel = _formatDocType(rawDocType);
+            const docTypeEl = document.getElementById("sc-result-doctype");
+            if (docTypeLabel && docTypeEl) {
+                docTypeEl.textContent = docTypeLabel;
+                docTypeRow.style.display = "flex";
+            }
         };
         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";
+            iconWrap.style.cssText += `background:${this.theme.errorBg};border:3px solid ${this.theme.error};color:${this.theme.error};font-size:32px;`;
+            resultCard.style.borderColor = this.theme.error;
             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;
+            statusBadge.textContent = "Not verified";
+            title.textContent = "Verification Unsuccessful";
+            desc.textContent = "We were unable to confirm your identity this time.";
+            // Show a clean, actionable reason — never raw technical strings
+            const safeReason = _sanitizeUserMessage(reason);
+            if (safeReason) {
+                failureMsg.textContent = safeReason;
                 failureMsg.style.display = "block";
             }
+            // Show retry button on failure
+            retryBtn.style.display = "block";
         };
         const poll = async () => {
             if (this.isDestroyed)
@@ -1376,34 +1627,32 @@ export class SmartComplyFlow {
                 const result = await this.sdk.liveness.pollResult(entryId);
                 if (result.status === "passed") {
                     onResolved("passed");
-                    applyPassed();
+                    applyPassed(result);
                     return;
                 }
                 if (result.status === "failed") {
-                    onResolved(result.status);
-                    const reason = result.failure_reason || "Verification could not be completed. Please try again.";
-                    applyFailed(reason);
+                    onResolved("failed");
+                    applyFailed(result.failure_reason || null);
                     return;
                 }
-                // Still pending/processing — schedule next poll if budget remains
+                // Still processing — schedule next poll
                 if (polls < MAX_POLLS && !this.isDestroyed) {
                     this._pollStatusTimer = setTimeout(poll, 3000);
                 }
                 else if (!this.isDestroyed) {
-                    applyTimeout(); // budget exhausted — stop spinner, show timeout state
+                    applyTimeout();
                 }
             }
             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
+                    applyTimeout();
                 }
             }
         };
-        // First poll after 4 s — gives Celery task time to complete
+        // First poll after 4s — gives Celery task time to start
         this._pollStatusTimer = setTimeout(poll, 4000);
     }
     renderResult(_container) {
@@ -1416,23 +1665,51 @@ export class SmartComplyFlow {
             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};
     `;
@@ -1444,22 +1721,16 @@ export 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();
@@ -1472,6 +1743,7 @@ export class SmartComplyFlow {
     // ─────────────────────────────────────────────────────────────────
     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};
@@ -1481,6 +1753,7 @@ export 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;
@@ -1489,6 +1762,7 @@ export 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;
@@ -1501,6 +1775,7 @@ export 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;
@@ -1510,6 +1785,8 @@ export 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;
@@ -1518,6 +1795,7 @@ export class SmartComplyFlow {
         // Close button
         const closeBtn = document.createElement("button");
         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;
@@ -1564,6 +1842,7 @@ export 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};
@@ -1655,7 +1934,7 @@ export class SmartComplyFlow {
         const allFields = Object.values(channels)
             .flat()
             .flatMap((ch) => ch.fields || []);
-        return allFields.some((f) => f.type === "upload");
+        return allFields.some((f) => isUploadFieldType(f.type));
     }
     updateProgress() {
         const isDocFlow = this.isDocumentFlow();
@@ -1742,6 +2021,12 @@ export 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;
       }