central-auth-js-sdk 1.0.11 → 1.0.12

package/core/api.js

@@ -193,6 +193,32 @@ export function createApi(baseUrl = DEFAULT_BASE, options = {}) {
       if (appIdentifier) fd.append('app_identifier', appIdentifier);
       return request('POST', '/login/email/fr', fd);
     },
+
+    // --- Phone Face Capture ---
+
+    /** POST /fr/session — Create a phone capture session (QR fallback) */
+    async createCaptureSession() {
+      return request('POST', '/fr/session', null);
+    },
+
+    /**
+     * GET /fr/capture/result — Poll for phone-captured face image
+     * Returns { status: 'waiting' } on 202 or { status: 'ready', image } on 200.
+     * Throws on 404/403 (expired/invalid).
+     */
+    async pollCaptureResult(sessionId, secret) {
+      const url = `${base}/fr/capture/result?sid=${encodeURIComponent(sessionId)}&secret=${encodeURIComponent(secret)}`;
+      const res = await fetch(url);
+      const text = await res.text();
+      let data = null;
+      try { data = text ? JSON.parse(text) : null; } catch { data = { _raw: text }; }
+      if (res.status === 200 && data?.status === 'ready') return data;
+      if (res.status === 202) return data;
+      const err = new Error(data?.error || 'Session expired or invalid');
+      err.status = res.status;
+      err.data = data;
+      throw err;
+    },
   };
 }
 
@@ -224,3 +250,14 @@ export function dataUrlToFile(dataUrl, filename = 'capture.jpg') {
   while (n--) u8[n] = bstr.charCodeAt(n);
   return new File([u8], filename, { type: mime });
 }
+
+/**
+ * Convert a raw base64 string (no data: prefix) to a File for FormData
+ */
+export function base64ToFile(base64, filename = 'phone-capture.jpg') {
+  const byteString = atob(base64);
+  const ab = new ArrayBuffer(byteString.length);
+  const ia = new Uint8Array(ab);
+  for (let i = 0; i < byteString.length; i++) ia[i] = byteString.charCodeAt(i);
+  return new File([ab], filename, { type: 'image/jpeg' });
+}

package/index.js

@@ -14,7 +14,7 @@
 export { mount } from './signup.js';
 export { FlowController, STEPS } from './core/flow.js';
 export { StateManager } from './core/state.js';
-export { createApi, dataUrlToFile } from './core/api.js';
+export { createApi, dataUrlToFile, base64ToFile } from './core/api.js';
 export { mountLogin } from './login.js';
 export { initializeAuth, startSignup, startLogin } from './auth.js';
 export { applyTheme, THEME_PRESETS } from './theme.js';

package/login.js

@@ -302,6 +302,7 @@ export function mountLogin(container, options = {}) {
       onSocialRedirect: handlers.onSocialRedirect,
       onSignUp: handlers.onSignUp,
       onSwitchToOtp: handlers.onSwitchToOtp,
+      api,
     });
     layout.setContent(screen);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "central-auth-js-sdk",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "description": "Vanilla JS sign-up and login flow SDK — embeddable auth UI with configurable methods",
   "type": "module",
   "main": "index.js",
@@ -31,5 +31,8 @@
   "license": "MIT",
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "qrcode": "^1.5.4"
   }
 }

package/signup.js

@@ -283,6 +283,7 @@ export function mount(container, options = {}) {
     onContinue: typeof onContinue === 'function' ? onContinue : () => {},
     onSwitchToLogin: typeof onSwitchToLogin === 'function' ? onSwitchToLogin : () => {},
     onBackToApp: typeof onBack === 'function' ? onBack : () => { cleanupTheme(); layout.root.remove(); },
+    api,
   };
 
   function render() {

package/styles.css

@@ -772,6 +772,133 @@
 
 .wf-face-actions { display: flex; flex-direction: column; gap: 0.625rem; }
 
+/* ============================= PHONE CAPTURE (QR FALLBACK) ============================= */
+
+.wf-phone-capture {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  align-items: center;
+  text-align: center;
+}
+
+.wf-phone-capture-header { display: flex; flex-direction: column; align-items: center; gap: 0.375rem; }
+.wf-phone-capture-title { font-size: 1.0625rem; font-weight: 700; color: var(--wf-fg); margin: 0; }
+.wf-phone-capture-desc { font-size: 0.8125rem; color: var(--wf-muted); margin: 0; max-width: 22rem; line-height: 1.45; }
+
+.wf-phone-capture-loading {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 0.75rem;
+  padding: 2rem 0;
+}
+.wf-phone-capture-loading p { font-size: 0.8125rem; color: var(--wf-muted); margin: 0; }
+
+.wf-spinner {
+  width: 2rem;
+  height: 2rem;
+  border: 3px solid var(--wf-border);
+  border-top-color: var(--wf-primary);
+  border-radius: 50%;
+  animation: wf-spin 0.7s linear infinite;
+}
+@keyframes wf-spin { to { transform: rotate(360deg); } }
+
+.wf-phone-capture-body {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 1rem;
+  animation: wf-screen-in 0.3s var(--wf-ease) both;
+}
+
+.wf-qr-code {
+  padding: 0.75rem;
+  background: #fff;
+  border-radius: var(--wf-radius);
+  border: 1px solid var(--wf-border);
+  box-shadow: 0 2px 8px rgba(0,0,0,0.06);
+  line-height: 0;
+}
+.wf-qr-code img { width: 180px; height: 180px; border-radius: 4px; }
+
+.wf-btn-copy-link {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.375rem;
+  padding: 0.375rem 0.75rem;
+  font-size: 0.75rem;
+  font-weight: 600;
+  font-family: var(--wf-font);
+  color: var(--wf-primary);
+  background: transparent;
+  border: 1px solid var(--wf-border);
+  border-radius: var(--wf-radius-sm);
+  cursor: pointer;
+  transition: all 0.15s var(--wf-ease);
+}
+.wf-btn-copy-link:hover { border-color: var(--wf-primary); background: var(--wf-muted-bg, rgba(0,0,0,0.03)); }
+.wf-btn-copy-link svg { width: 0.875rem; height: 0.875rem; }
+.wf-btn-copy-link-done { color: var(--wf-success); border-color: var(--wf-success); }
+
+.wf-pin-section { display: flex; flex-direction: column; align-items: center; gap: 0.5rem; }
+.wf-pin-label { font-size: 0.75rem; color: var(--wf-muted); margin: 0; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; }
+
+.wf-pin-display {
+  display: flex;
+  gap: 0.375rem;
+}
+.wf-pin-digit {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 2.25rem;
+  height: 2.75rem;
+  background: var(--wf-input-bg, var(--wf-card));
+  border: 2px solid var(--wf-primary);
+  border-radius: var(--wf-radius-sm);
+  font-size: 1.375rem;
+  font-weight: 700;
+  color: var(--wf-fg);
+  font-family: var(--wf-font);
+}
+
+.wf-capture-meta { display: flex; flex-direction: column; align-items: center; gap: 0.25rem; }
+.wf-capture-timer { font-size: 0.75rem; color: var(--wf-muted); margin: 0; font-variant-numeric: tabular-nums; }
+.wf-capture-status { font-size: 0.8125rem; color: var(--wf-fg-soft); margin: 0; }
+.wf-capture-status-done { color: var(--wf-success); font-weight: 600; }
+
+.wf-phone-capture-error { text-align: center; padding: 1rem 0; }
+
+.wf-phone-capture-success {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 0.75rem;
+  padding: 1.5rem 0;
+  animation: wf-success-pop 0.5s var(--wf-ease-spring) both;
+}
+.wf-capture-success-icon {
+  width: 3rem;
+  height: 3rem;
+  border-radius: 50%;
+  background: var(--wf-success-bg);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+.wf-capture-success-icon svg { width: 1.5rem; height: 1.5rem; color: var(--wf-success); }
+
+.wf-phone-capture-actions {
+  display: flex;
+  gap: 0.5rem;
+  width: 100%;
+  justify-content: center;
+}
+
+.wf-phone-fallback-link { text-align: center; margin-top: 0.25rem; }
+
 /* ============================= SUCCESS ============================= */
 
 .wf-screen-success { align-items: center; text-align: center; }

package/ui/screens/face-registration.js

@@ -1,15 +1,18 @@
 /**
  * Face Registration Screen — Camera capture for biometric verification
- * v2.0 — warm, modern design
+ * Falls back to phone QR capture when no webcam is available.
  */
 
+import { hasWebcam } from '../webcam-utils.js';
+import { createPhoneCaptureComponent } from './phone-capture.js';
+
 const SCAN_FACE = 'M9 12l2 2 4-4m5.618-4.016A11.955 11.955 0 0112 2.944a11.955 11.955 0 01-8.618 3.04A12.02 12.02 0 003 9c0 5.591 3.824 10.29 9 11.622 5.176-1.332 9-6.03 9-11.622 0-1.042-.133-2.052-.382-3.016z';
 const CAMERA_ICON = 'M3 9a2 2 0 012-2h.93a2 2 0 001.664-.89l.812-1.22A2 2 0 0110.07 4h3.86a2 2 0 011.664.89l.812 1.22A2 2 0 0018.07 7H19a2 2 0 012 2v9a2 2 0 01-2 2H5a2 2 0 01-2-2V9z M15 13a3 3 0 11-6 0 3 3 0 016 0z M19 10v1a1 1 0 01-1 1H6a1 1 0 01-1-1v-1';
 const ARROW_LEFT = 'M19 12H5m7 7l-7-7 7-7';
 const ARROW_RIGHT = 'M5 12h14m-7-7l7 7-7 7';
 const ROTATE_ICON = 'M1 4v6h6M23 20v-6h-6';
 
-export function createFaceRegistrationScreen(onNext, onBack) {
+export function createFaceRegistrationScreen(onNext, onBack, api) {
   const wrap = document.createElement('div');
   wrap.className = 'wf-screen';
 
@@ -57,9 +60,11 @@ export function createFaceRegistrationScreen(onNext, onBack) {
           </button>
         </div>
       </div>
+      ${api ? '<p class="wf-footer-link wf-phone-fallback-link" id="wf-use-phone"><button type="button" class="wf-link" data-action="use-phone">Use phone instead</button></p>' : ''}
     </div>
   `;
 
+  const cameraView = wrap.querySelector('#wf-camera-view');
   const placeholder = wrap.querySelector('#wf-camera-placeholder');
   const video = wrap.querySelector('#wf-video');
   const captured = wrap.querySelector('#wf-captured');
@@ -70,13 +75,58 @@ export function createFaceRegistrationScreen(onNext, onBack) {
   const captureBtn = wrap.querySelector('#wf-capture-btn');
   const capturedActions = wrap.querySelector('#wf-captured-actions');
   const backOnly = wrap.querySelector('#wf-back-only');
+  const faceArea = wrap.querySelector('.wf-face-area');
+
+  const usePhoneLink = wrap.querySelector('#wf-use-phone');
 
   let stream = null;
+  let phoneCaptureRef = null;
+
+  function stopStream() {
+    if (stream) { stream.getTracks().forEach((t) => t.stop()); stream = null; }
+  }
+
+  function showPhoneCapture(canSwitchBack) {
+    if (!api) return;
+    stopStream();
+    cameraView.classList.add('hidden');
+    errorEl.classList.add('hidden');
+    captureBtn.classList.add('hidden');
+    capturedActions.classList.add('hidden');
+    captured.classList.add('hidden');
+    backOnly.classList.add('hidden');
+    if (usePhoneLink) usePhoneLink.classList.add('hidden');
+
+    if (phoneCaptureRef) { phoneCaptureRef.destroy(); phoneCaptureRef = null; }
+    const cancelAction = canSwitchBack ? () => switchToCamera() : onBack;
+    phoneCaptureRef = createPhoneCaptureComponent(api, onNext, cancelAction);
+    faceArea.insertBefore(phoneCaptureRef.element, faceArea.querySelector('.wf-face-actions'));
+  }
+
+  function switchToCamera() {
+    if (phoneCaptureRef) { phoneCaptureRef.destroy(); phoneCaptureRef.element.remove(); phoneCaptureRef = null; }
+    cameraView.classList.remove('hidden');
+    placeholder.classList.remove('hidden');
+    video.classList.add('hidden');
+    overlay.classList.add('hidden');
+    captureBtn.classList.add('hidden');
+    capturedActions.classList.add('hidden');
+    captured.classList.add('hidden');
+    backOnly.classList.remove('hidden');
+    if (usePhoneLink) usePhoneLink.classList.remove('hidden');
+  }
 
   async function startCamera() {
+    errorEl.classList.add('hidden');
+    errorEl.textContent = '';
+
+    const webcamAvailable = await hasWebcam();
+    if (!webcamAvailable) {
+      showPhoneCapture(false);
+      return;
+    }
+
     try {
-      errorEl.classList.add('hidden');
-      errorEl.textContent = '';
       stream = await navigator.mediaDevices.getUserMedia({ video: { facingMode: 'user' } });
       video.srcObject = stream;
       video.classList.remove('hidden');
@@ -84,9 +134,9 @@ export function createFaceRegistrationScreen(onNext, onBack) {
       overlay.classList.remove('hidden');
       captureBtn.classList.remove('hidden');
       backOnly.classList.add('hidden');
+      if (usePhoneLink) usePhoneLink.classList.remove('hidden');
     } catch {
-      errorEl.textContent = 'Camera access denied. Please enable camera permissions.';
-      errorEl.classList.remove('hidden');
+      showPhoneCapture(false);
     }
   }
 
@@ -121,5 +171,8 @@ export function createFaceRegistrationScreen(onNext, onBack) {
   });
   wrap.querySelector('[data-action="back"]').addEventListener('click', onBack);
 
+  const usePhoneBtn = wrap.querySelector('[data-action="use-phone"]');
+  if (usePhoneBtn) usePhoneBtn.addEventListener('click', () => showPhoneCapture(true));
+
   return wrap;
 }

package/ui/screens/index.js

@@ -25,6 +25,7 @@ export function createScreen(step, state, flow, callbacks) {
     onContinue,
     onSwitchToLogin,
     onBackToApp,
+    api,
   } = callbacks;
 
   switch (step) {
@@ -55,7 +56,8 @@ export function createScreen(step, state, flow, callbacks) {
     case STEPS.FACE:
       return createFaceRegistrationScreen(
         (capture) => onFaceSubmit(capture),
-        onBack
+        onBack,
+        api
       );
 
     case STEPS.SUCCESS:

package/ui/screens/login/frs.js

@@ -1,8 +1,11 @@
 /**
  * Login — Face verification (FRS) as second factor or email+face only
- * v2.0 — warm, modern design
+ * Falls back to phone QR capture when no webcam is available.
  */
 
+import { hasWebcam } from '../../webcam-utils.js';
+import { createPhoneCaptureComponent } from '../phone-capture.js';
+
 const SCAN_FACE = 'M9 12l2 2 4-4m5.618-4.016A11.955 11.955 0 0112 2.944a11.955 11.955 0 01-8.618 3.04A12.02 12.02 0 003 9c0 5.591 3.824 10.29 9 11.622 5.176-1.332 9-6.03 9-11.622 0-1.042-.133-2.052-.382-3.016z';
 const CAMERA_ICON = 'M3 9a2 2 0 012-2h.93a2 2 0 001.664-.89l.812-1.22A2 2 0 0110.07 4h3.86a2 2 0 011.664.89l.812 1.22A2 2 0 0018.07 7H19a2 2 0 012 2v9a2 2 0 01-2 2H5a2 2 0 01-2-2V9z M15 13a3 3 0 11-6 0 3 3 0 016 0z M19 10v1a1 1 0 01-1 1H6a1 1 0 01-1-1v-1';
 const ARROW_LEFT = 'M19 12H5m7 7l-7-7 7-7';
@@ -10,7 +13,7 @@ const ARROW_RIGHT = 'M5 12h14m-7-7l7 7-7 7';
 const ROTATE_ICON = 'M1 4v6h6M23 20v-6h-6';
 
 export function createLoginFrsScreen(onNext, onBack, opts = {}) {
-  const { onSwitchToOtp, showOtpFallback } = opts;
+  const { onSwitchToOtp, showOtpFallback, api } = opts;
   const wrap = document.createElement('div');
   wrap.className = 'wf-screen';
 
@@ -64,34 +67,81 @@ export function createLoginFrsScreen(onNext, onBack, opts = {}) {
           </button>
         </div>
       </div>
+      ${api ? '<p class="wf-footer-link wf-phone-fallback-link" id="wf-login-use-phone"><button type="button" class="wf-link" data-action="use-phone">Use phone instead</button></p>' : ''}
       ${otpFallbackHtml}
     </div>
   `;
 
+  const cameraView = wrap.querySelector('#wf-login-camera-view');
   const placeholder = wrap.querySelector('#wf-login-camera-placeholder');
   const video = wrap.querySelector('#wf-login-video');
   const captured = wrap.querySelector('#wf-login-captured');
   const overlay = wrap.querySelector('#wf-login-face-overlay');
   const canvas = wrap.querySelector('#wf-login-canvas');
   const errorEl = wrap.querySelector('#wf-login-camera-error');
+  const faceArea = wrap.querySelector('.wf-face-area');
+
+  const usePhoneLink = wrap.querySelector('#wf-login-use-phone');
 
   let stream = null;
+  let phoneCaptureRef = null;
+
+  function stopStream() {
+    if (stream) { stream.getTracks().forEach((t) => t.stop()); stream = null; }
+  }
+
+  function showPhoneCapture(canSwitchBack) {
+    if (!api) return;
+    stopStream();
+    cameraView.classList.add('hidden');
+    errorEl.classList.add('hidden');
+    wrap.querySelector('#wf-login-capture-btn').classList.add('hidden');
+    wrap.querySelector('#wf-login-captured-actions').classList.add('hidden');
+    captured.classList.add('hidden');
+    wrap.querySelector('#wf-login-back-only').classList.add('hidden');
+    if (usePhoneLink) usePhoneLink.classList.add('hidden');
+
+    if (phoneCaptureRef) { phoneCaptureRef.destroy(); phoneCaptureRef = null; }
+    const cancelAction = canSwitchBack ? () => switchToCamera() : onBack;
+    phoneCaptureRef = createPhoneCaptureComponent(api, onNext, cancelAction);
+    const actionsEl = faceArea.querySelector('.wf-face-actions');
+    faceArea.insertBefore(phoneCaptureRef.element, actionsEl);
+  }
 
-  function startCamera() {
-    navigator.mediaDevices.getUserMedia({ video: { facingMode: 'user' } })
-      .then((s) => {
-        stream = s;
-        video.srcObject = s;
-        video.classList.remove('hidden');
-        placeholder.classList.add('hidden');
-        overlay.classList.remove('hidden');
-        wrap.querySelector('#wf-login-capture-btn').classList.remove('hidden');
-        errorEl.classList.add('hidden');
-      })
-      .catch(() => {
-        errorEl.textContent = 'Camera access denied. Please enable camera permissions.';
-        errorEl.classList.remove('hidden');
-      });
+  function switchToCamera() {
+    if (phoneCaptureRef) { phoneCaptureRef.destroy(); phoneCaptureRef.element.remove(); phoneCaptureRef = null; }
+    cameraView.classList.remove('hidden');
+    placeholder.classList.remove('hidden');
+    video.classList.add('hidden');
+    overlay.classList.add('hidden');
+    wrap.querySelector('#wf-login-capture-btn').classList.add('hidden');
+    wrap.querySelector('#wf-login-captured-actions').classList.add('hidden');
+    captured.classList.add('hidden');
+    wrap.querySelector('#wf-login-back-only').classList.remove('hidden');
+    if (usePhoneLink) usePhoneLink.classList.remove('hidden');
+  }
+
+  async function startCamera() {
+    errorEl.classList.add('hidden');
+    errorEl.textContent = '';
+
+    const webcamAvailable = await hasWebcam();
+    if (!webcamAvailable) {
+      showPhoneCapture(false);
+      return;
+    }
+
+    try {
+      stream = await navigator.mediaDevices.getUserMedia({ video: { facingMode: 'user' } });
+      video.srcObject = stream;
+      video.classList.remove('hidden');
+      placeholder.classList.add('hidden');
+      overlay.classList.remove('hidden');
+      wrap.querySelector('#wf-login-capture-btn').classList.remove('hidden');
+      if (usePhoneLink) usePhoneLink.classList.remove('hidden');
+    } catch {
+      showPhoneCapture(false);
+    }
   }
 
   function captureImage() {
@@ -130,5 +180,8 @@ export function createLoginFrsScreen(onNext, onBack, opts = {}) {
     switchToOtpBtn.addEventListener('click', () => onSwitchToOtp());
   }
 
+  const usePhoneBtn = wrap.querySelector('[data-action="use-phone"]');
+  if (usePhoneBtn) usePhoneBtn.addEventListener('click', () => showPhoneCapture(true));
+
   return wrap;
 }

package/ui/screens/login/index.js

@@ -27,6 +27,7 @@ export function createLoginScreen(stepId, flow, state, config, handlers) {
     onSocialRedirect,
     onSignUp,
     onSwitchToOtp,
+    api,
   } = handlers;
 
   const enabledMethods = getEnabledLoginMethods(config);
@@ -91,6 +92,7 @@ export function createLoginScreen(stepId, flow, state, config, handlers) {
         {
           onSwitchToOtp,
           showOtpFallback: flow.currentMethod === LOGIN_METHODS.EMAIL_FRS,
+          api,
         }
       );
 

package/ui/screens/phone-capture.js

@@ -0,0 +1,278 @@
+/**
+ * Phone Face Capture — QR code fallback when desktop webcam is unavailable.
+ * Creates a session via POST /fr/session, displays QR + PIN, polls for result.
+ * Returns { element, destroy } — embed `element` in the face capture screen area.
+ */
+
+import QRCode from 'qrcode';
+
+const POLL_INTERVAL = 2000;
+const MAX_CONSECUTIVE_ERRORS = 3;
+const PHONE_ICON = 'M12 18h.01M8 21h8a2 2 0 002-2V5a2 2 0 00-2-2H8a2 2 0 00-2 2v14a2 2 0 002 2z';
+const REFRESH_ICON = 'M1 4v6h6M23 20v-6h-6';
+const COPY_ICON = 'M8 5H6a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2v-1M8 5a2 2 0 002 2h2a2 2 0 002-2M8 5a2 2 0 012-2h2a2 2 0 012 2m0 0h2a2 2 0 012 2v3m2 4H10m0 0l3-3m-3 3l3 3';
+
+/**
+ * @param {Object} api - SDK api instance (needs createCaptureSession, pollCaptureResult)
+ * @param {Function} onCaptured - Called with data URL when phone capture succeeds
+ * @param {Function} onCancel - Called when user clicks Cancel
+ * @returns {{ element: HTMLElement, destroy: Function }}
+ */
+export function createPhoneCaptureComponent(api, onCaptured, onCancel) {
+  let destroyed = false;
+  let pollTimer = null;
+  let countdownTimer = null;
+  let session = null;
+
+  const wrap = document.createElement('div');
+  wrap.className = 'wf-phone-capture';
+
+  wrap.innerHTML = `
+    <div class="wf-phone-capture-header">
+      <div class="wf-icon-box">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="${PHONE_ICON}"/></svg>
+      </div>
+      <h3 class="wf-phone-capture-title">Use your phone</h3>
+      <p class="wf-phone-capture-desc">Scan the QR code with your phone and enter the PIN to capture your face</p>
+    </div>
+
+    <div class="wf-phone-capture-loading" id="wf-pc-loading">
+      <div class="wf-spinner"></div>
+      <p>Creating session…</p>
+    </div>
+
+    <div class="wf-phone-capture-body hidden" id="wf-pc-body">
+      <div class="wf-qr-code">
+        <img id="wf-pc-qr" alt="QR Code" />
+      </div>
+      <button type="button" class="wf-btn-copy-link" id="wf-pc-copy-link">
+        <svg class="wf-icon-sm" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="${COPY_ICON}"/></svg>
+        <span>Copy link</span>
+      </button>
+
+      <div class="wf-pin-section">
+        <p class="wf-pin-label">Enter this PIN on your phone</p>
+        <div class="wf-pin-display" id="wf-pc-pin"></div>
+      </div>
+
+      <div class="wf-capture-meta">
+        <p class="wf-capture-timer" id="wf-pc-timer"></p>
+        <p class="wf-capture-status" id="wf-pc-status">Waiting for phone capture…</p>
+      </div>
+    </div>
+
+    <div class="wf-phone-capture-error hidden" id="wf-pc-error">
+      <p class="wf-error" id="wf-pc-error-msg"></p>
+    </div>
+
+    <div class="wf-phone-capture-success hidden" id="wf-pc-success">
+      <div class="wf-capture-success-icon">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="M20 6L9 17l-5-5"/></svg>
+      </div>
+      <p class="wf-capture-status wf-capture-status-done">Face captured!</p>
+    </div>
+
+    <div class="wf-phone-capture-actions">
+      <button type="button" class="wf-btn wf-btn-outline wf-btn-lg" id="wf-pc-cancel">Cancel</button>
+      <button type="button" class="wf-btn wf-btn-primary wf-btn-lg hidden" id="wf-pc-retry">
+        <svg class="wf-icon-sm" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="${REFRESH_ICON}"/></svg>
+        Try Again
+      </button>
+    </div>
+  `;
+
+  const loadingEl = wrap.querySelector('#wf-pc-loading');
+  const bodyEl = wrap.querySelector('#wf-pc-body');
+  const qrImg = wrap.querySelector('#wf-pc-qr');
+  const pinEl = wrap.querySelector('#wf-pc-pin');
+  const timerEl = wrap.querySelector('#wf-pc-timer');
+  const statusEl = wrap.querySelector('#wf-pc-status');
+  const errorWrap = wrap.querySelector('#wf-pc-error');
+  const errorMsg = wrap.querySelector('#wf-pc-error-msg');
+  const successEl = wrap.querySelector('#wf-pc-success');
+  const cancelBtn = wrap.querySelector('#wf-pc-cancel');
+  const retryBtn = wrap.querySelector('#wf-pc-retry');
+  const copyLinkBtn = wrap.querySelector('#wf-pc-copy-link');
+  const copyLinkLabel = copyLinkBtn.querySelector('span');
+
+  cancelBtn.addEventListener('click', () => {
+    destroy();
+    onCancel();
+  });
+
+  retryBtn.addEventListener('click', () => {
+    startSession();
+  });
+
+  copyLinkBtn.addEventListener('click', async () => {
+    if (!session?.captureUrl) return;
+    try {
+      await navigator.clipboard.writeText(session.captureUrl);
+      copyLinkLabel.textContent = 'Copied!';
+      copyLinkBtn.classList.add('wf-btn-copy-link-done');
+      setTimeout(() => {
+        copyLinkLabel.textContent = 'Copy link';
+        copyLinkBtn.classList.remove('wf-btn-copy-link-done');
+      }, 2000);
+    } catch {
+      copyLinkLabel.textContent = 'Failed to copy';
+      setTimeout(() => { copyLinkLabel.textContent = 'Copy link'; }, 2000);
+    }
+  });
+
+  function showView(view) {
+    loadingEl.classList.add('hidden');
+    bodyEl.classList.add('hidden');
+    errorWrap.classList.add('hidden');
+    successEl.classList.add('hidden');
+    retryBtn.classList.add('hidden');
+    cancelBtn.classList.remove('hidden');
+
+    if (view === 'loading') loadingEl.classList.remove('hidden');
+    else if (view === 'body') bodyEl.classList.remove('hidden');
+    else if (view === 'error') { errorWrap.classList.remove('hidden'); retryBtn.classList.remove('hidden'); }
+    else if (view === 'success') { successEl.classList.remove('hidden'); cancelBtn.classList.add('hidden'); }
+  }
+
+  function renderPin(pin) {
+    pinEl.innerHTML = '';
+    for (const ch of pin) {
+      const span = document.createElement('span');
+      span.className = 'wf-pin-digit';
+      span.textContent = ch;
+      pinEl.appendChild(span);
+    }
+  }
+
+  function startCountdown(expiresAt) {
+    clearInterval(countdownTimer);
+    const expiry = new Date(expiresAt).getTime();
+
+    function tick() {
+      const remaining = Math.max(0, expiry - Date.now());
+      if (remaining <= 0) {
+        clearInterval(countdownTimer);
+        stopPolling();
+        showError('Session expired');
+        return;
+      }
+      const mins = Math.floor(remaining / 60000);
+      const secs = Math.floor((remaining % 60000) / 1000);
+      timerEl.textContent = `Expires in ${mins}:${String(secs).padStart(2, '0')}`;
+    }
+
+    tick();
+    countdownTimer = setInterval(tick, 1000);
+  }
+
+  function showError(msg) {
+    errorMsg.textContent = msg;
+    showView('error');
+  }
+
+  function stopPolling() {
+    clearTimeout(pollTimer);
+    pollTimer = null;
+  }
+
+  async function startSession() {
+    if (destroyed) return;
+    stopPolling();
+    clearInterval(countdownTimer);
+    showView('loading');
+
+    try {
+      const res = await api.createCaptureSession();
+      if (destroyed) return;
+      session = {
+        id: res.session_id,
+        secret: res.secret,
+        pin: res.pin,
+        captureUrl: res.capture_url,
+        expiresAt: res.expires_at,
+      };
+
+      const qrDataUrl = await QRCode.toDataURL(session.captureUrl, {
+        width: 220,
+        margin: 2,
+        color: { dark: '#1A1714', light: '#FFFFFF' },
+      });
+      if (destroyed) return;
+
+      qrImg.src = qrDataUrl;
+      renderPin(session.pin);
+      statusEl.textContent = 'Waiting for phone capture…';
+      showView('body');
+      startCountdown(session.expiresAt);
+      startPolling();
+    } catch (err) {
+      if (destroyed) return;
+      if (err?.status === 429) {
+        showError('Too many attempts. Please wait and try again.');
+      } else {
+        showError(err?.data?.error || err?.message || 'Failed to create capture session');
+      }
+    }
+  }
+
+  function startPolling() {
+    let consecutiveErrors = 0;
+    let backoff = POLL_INTERVAL;
+
+    async function poll() {
+      if (destroyed || !session) return;
+
+      try {
+        const res = await api.pollCaptureResult(session.id, session.secret);
+        if (destroyed) return;
+
+        if (res.status === 'ready' && res.image) {
+          stopPolling();
+          clearInterval(countdownTimer);
+          const dataUrl = `data:image/jpeg;base64,${res.image}`;
+          showView('success');
+          setTimeout(() => {
+            if (!destroyed) onCaptured(dataUrl);
+          }, 800);
+          return;
+        }
+
+        consecutiveErrors = 0;
+        backoff = POLL_INTERVAL;
+        pollTimer = setTimeout(poll, POLL_INTERVAL);
+      } catch (err) {
+        if (destroyed) return;
+        consecutiveErrors++;
+
+        if (err?.status === 404 || err?.status === 403) {
+          stopPolling();
+          clearInterval(countdownTimer);
+          showError('Session expired or invalid');
+          return;
+        }
+
+        if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
+          stopPolling();
+          clearInterval(countdownTimer);
+          showError('Connection issue. Please try again.');
+          return;
+        }
+
+        backoff = Math.min(backoff * 2, 8000);
+        pollTimer = setTimeout(poll, backoff);
+      }
+    }
+
+    pollTimer = setTimeout(poll, POLL_INTERVAL);
+  }
+
+  function destroy() {
+    destroyed = true;
+    stopPolling();
+    clearInterval(countdownTimer);
+  }
+
+  startSession();
+
+  return { element: wrap, destroy };
+}

package/ui/webcam-utils.js

@@ -0,0 +1,26 @@
+/**
+ * Webcam detection utilities
+ */
+
+/** Check if the device has at least one video input (webcam) */
+export async function hasWebcam() {
+  try {
+    if (!navigator.mediaDevices || !navigator.mediaDevices.enumerateDevices) return false;
+    const devices = await navigator.mediaDevices.enumerateDevices();
+    return devices.some((d) => d.kind === 'videoinput');
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Attempt to get a user-facing camera stream.
+ * Returns the MediaStream on success, or null on failure.
+ */
+export async function tryGetUserMedia() {
+  try {
+    return await navigator.mediaDevices.getUserMedia({ video: { facingMode: 'user' } });
+  } catch {
+    return null;
+  }
+}