central-auth-js-sdk 1.0.11 → 1.0.13

package/INTEGRATION_GUIDE.md

@@ -96,6 +96,7 @@ Call once (e.g. at app load) to set defaults. Returns `{ startSignup, startLogin
 | `loginMethods` | object | — | Default login methods (see Login config) |
 | `frsAsSecondFactor` | boolean | `false` | Default: require face verification after primary auth |
 | `enableFaceRegistration` | boolean | `true` | Whether sign-up includes face registration step |
+| `onBack` | function | — | Default callback when user clicks ← Back on the first screen of signup/login (see [§ 9](#9-returning-to-the-parent-application)) |
 
 **Environments:** The SDK uses only `env` to choose the API base URL:
 
@@ -142,6 +143,7 @@ Starts the **sign-up flow** (email + name → verify → mobile → verify → p
 | `enableFaceRegistration` | boolean | no | Include face registration step (default from init or `true`) |
 | **`onSignupComplete(payload)`** | function | no | Called **once** when signup completes. `payload`: `email`, `mobile`, `userId` + any fields from final API (e.g. `access_token`, `refresh_token`). |
 | **`onContinue()`** | function | no | Called when user clicks **Continue to application** on the success screen. Use to unmount and redirect. |
+| **`onBack()`** | function | no | Called when user clicks **← Back** on the **first screen** of signup. Use to unmount the SDK and return to your app. See [§ 9](#9-returning-to-the-parent-application). |
 | **`onSwitchToLogin()`** | function | no | Called when user clicks **Sign in** (e.g. “Already have an account? Sign in”). Use to unmount signup and start the login flow in the **same container** (e.g. login + FRS). |
 
 **Returns:** `{ unmount, getState, getFlow, getCurrentStep }` or `null` if container is invalid.
@@ -163,6 +165,10 @@ const instance = startSignup({
     instance.unmount();
     redirectToDashboard();
   },
+  onBack() {
+    instance.unmount();
+    showYourAppScreen();
+  },
   onSwitchToLogin() {
     instance.unmount();
     startLogin({ container: '#auth-container', env: 'dev', appIdentifier: 'my-app', loginMethods: { emailFrs: true }, onContinue: goToApp, onSignUp: showSignup });
@@ -266,6 +272,7 @@ Starts the **login flow**. If the parent enables **only one** login method, the
 | **`onSignUp()`** | function | no | Called when user clicks **Sign up** on the login screen (e.g. unmount login and start signup in the **same container**). |
 | **`onLoginComplete(payload)`** | function | no | Called **once** when login completes. `payload`: `identifier` + any fields from final API (e.g. `access_token`, `refresh_token`). |
 | **`onContinue()`** | function | no | Called when user clicks **Continue to application** on the success screen. |
+| **`onBack()`** | function | no | Called when user clicks **← Back** on the **first screen** of login. Use to unmount the SDK and return to your app. See [§ 9](#9-returning-to-the-parent-application). |
 
 **Login methods** (`loginMethods`):
 
@@ -298,6 +305,10 @@ startLogin({
     instance.unmount();
     redirectToApp();
   },
+  onBack() {
+    instance.unmount();
+    redirectToApp();
+  },
   onSignUp() {
     instance.unmount();
     startSignup({ container: '#auth-container', env: 'dev', appIdentifier: '...', onContinue: goToApp, onSwitchToLogin: showLoginFrs });
@@ -321,6 +332,7 @@ startLogin({
   frsAsSecondFactor: true,
   onLoginComplete(payload) { /* ... */ },
   onContinue() { /* ... */ },
+  onBack() { /* unmount + return to parent app */ },
   onSignUp() { /* ... */ },
 });
 ```
@@ -372,16 +384,79 @@ You can also read **`instance.getState()`** after the flow completes; it include
 
 ## 9. Returning to the parent application
 
-When the user clicks **Continue to application** on the success screen, the SDK calls **`onContinue()`** if you provided it. Use it to unmount the SDK and show your app (e.g. redirect or switch view):
+The SDK does **not** automatically navigate your app when the user leaves auth. Your parent app is responsible for showing/hiding the auth container and routing the user back to your own UI. Use the callbacks below.
+
+### Two kinds of “Back”
+
+| Where | What happens |
+|-------|----------------|
+| **First screen** (signup email entry, login method picker, or single-method identifier screen) | **← Back** calls **`onBack()`** — intended to leave auth and return to your app |
+| **Later steps** (password, OTP, face capture, etc.) | **← Back** goes to the **previous step inside the SDK** only. Does **not** call `onBack()` |
+
+The first-screen back button is always shown. What happens when it is clicked depends on whether you pass **`onBack`**.
+
+### If you omit `onBack`
+
+The SDK uses a **default**: it unmounts itself (removes its UI from the container and cleans up theme). It does **not** show your app’s main screen, change routes, or hide overlays — you must do that yourself if needed.
+
+### What the parent app should do (recommended)
+
+Define one helper (e.g. `returnToApp`) and pass it to **`onBack`** and usually **`onContinue`** as well:
+
+```javascript
+let authInstance = null;
+
+function returnToApp() {
+  if (authInstance) authInstance.unmount();
+  authInstance = null;
+  document.getElementById('auth-container').style.display = 'none';
+  document.getElementById('app-root').style.display = 'block';
+  // or: router.push('/'); window.history.back(); etc.
+}
+
+authInstance = startLogin({
+  container: '#auth-container',
+  env: 'dev',
+  loginMethods: { emailPassword: true },
+  onBack: returnToApp,
+  onContinue: returnToApp,
+  onLoginComplete(payload) {
+    saveToken(payload.access_token);
+    returnToApp();
+  },
+});
+```
+
+**Typical steps inside `returnToApp` (or equivalent):**
+
+1. Call **`instance.unmount()`** — removes SDK DOM and theme
+2. Clear your reference to the instance (`authInstance = null`)
+3. Hide the auth container and show your main app UI (or navigate with your router)
+
+You can set **`onBack`** once in **`initializeAuth({ onBack: returnToApp, ... })`** and reuse it in `startSignup` / `startLogin` (per-call config overrides defaults).
+
+### Success screen — `onContinue()`
+
+When the user clicks **Continue to application** on the success screen, the SDK calls **`onContinue()`** if you provided it. Use the same pattern as **`onBack`**: unmount the SDK and show your app:
 
 ```javascript
 onContinue() {
   instance.unmount();
   window.location.href = '/dashboard';
-  // or: showYourAppView();
+  // or: returnToApp();
 }
 ```
 
+### Summary
+
+| Callback | When it fires | Parent app action |
+|----------|---------------|-------------------|
+| **`onBack()`** | User clicks ← Back on **first screen** | Unmount SDK + return to your app UI |
+| **`onContinue()`** | User clicks Continue on **success screen** | Unmount SDK + enter your app (often same as `onBack`) |
+| *(none)* | First-screen back, if `onBack` omitted | SDK unmounts only; parent UI unchanged |
+
+Returning to the parent app is **not automatic** beyond SDK unmount. Integrators should pass **`onBack`** (and **`onContinue`**) to fully control navigation in their application.
+
 ---
 
 ## 10. Full integration example
@@ -421,6 +496,7 @@ function showSignup() {
       goToApp();
     },
     onContinue: goToApp,
+    onBack: goToApp,
     onSwitchToLogin: showLoginFrs,
   });
 }
@@ -435,6 +511,7 @@ function showLoginFrs() {
       goToApp();
     },
     onContinue: goToApp,
+    onBack: goToApp,
     onSignUp: showSignup,
   });
 }
@@ -449,6 +526,7 @@ function showLogin(loginMethods = { emailPassword: true }) {
       goToApp();
     },
     onContinue: goToApp,
+    onBack: goToApp,
     onSignUp: showSignup,
   });
 }

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

@@ -208,6 +208,7 @@ export function mountLogin(container, options = {}) {
     const identifier = state.get('identifier');
     let apiResult = null;
 
+    layout.setLoading(true, 'Verifying your face…');
     try {
       if (method === LOGIN_METHODS.EMAIL_FRS) {
         apiResult = await api.loginEmailFr(identifier, file, null, config.appIdentifier);
@@ -230,6 +231,8 @@ export function mountLogin(container, options = {}) {
       const msg = err?.data?.error || err?.message || 'Verification failed';
       state.set('error', msg);
       showError(msg);
+    } finally {
+      layout.setLoading(false);
     }
   }
 
@@ -302,6 +305,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.13",
   "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

@@ -229,6 +229,7 @@ export function mount(container, options = {}) {
       showError('Please capture your face first.');
       return;
     }
+    layout.setLoading(true, 'Registering your face…');
     try {
       let apiResult = null;
       if (isSocial()) {
@@ -253,6 +254,8 @@ export function mount(container, options = {}) {
       const msg = err?.data?.error || err?.message || 'Face registration failed';
       state.set('error', msg);
       showError(msg);
+    } finally {
+      layout.setLoading(false);
     }
   }
 
@@ -283,6 +286,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

@@ -300,6 +300,67 @@
   display: none;
 }
 
+/* ============================= LOADING BAR ============================= */
+
+.wf-loading-bar {
+  height: 3px;
+  margin: -0.25rem 0 1rem;
+  border-radius: 999px;
+  background: var(--wf-muted-bg, rgba(0, 0, 0, 0.06));
+  overflow: hidden;
+}
+
+.wf-loading-bar.hidden {
+  display: none;
+}
+
+.wf-loading-bar-indeterminate {
+  height: 100%;
+  width: 40%;
+  border-radius: 999px;
+  background: linear-gradient(90deg, var(--wf-primary-grad-start) 0%, var(--wf-primary) 50%, var(--wf-primary-grad-end) 100%);
+  animation: wf-loading-slide 1.2s ease-in-out infinite;
+}
+
+@keyframes wf-loading-slide {
+  0% { transform: translateX(-100%); }
+  100% { transform: translateX(350%); }
+}
+
+.wf-loading-status {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  margin-bottom: 1rem;
+  padding: 0.5rem 0.75rem;
+  border-radius: var(--wf-radius);
+  background: var(--wf-muted-bg, rgba(0, 0, 0, 0.04));
+  color: var(--wf-fg-soft);
+  font-size: 0.8125rem;
+  font-weight: 500;
+}
+
+.wf-loading-status.hidden {
+  display: none;
+}
+
+.wf-loading-status::before {
+  content: '';
+  width: 1rem;
+  height: 1rem;
+  border: 2px solid var(--wf-border);
+  border-top-color: var(--wf-primary);
+  border-radius: 50%;
+  animation: wf-spin 0.7s linear infinite;
+  flex-shrink: 0;
+}
+
+#wf-form-inner.wf-loading-active {
+  pointer-events: none;
+  opacity: 0.65;
+}
+
 /* ============================= PAGE FOOTER ============================= */
 
 .wf-page-footer {
@@ -772,6 +833,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/layout.js

@@ -45,6 +45,10 @@ export function createLayout(container) {
           </div>
         </div>
         <div class="wf-card-body">
+          <div class="wf-loading-bar hidden" id="wf-loading-bar" role="progressbar" aria-busy="false" aria-label="Loading">
+            <div class="wf-loading-bar-indeterminate"></div>
+          </div>
+          <div class="wf-loading-status hidden" id="wf-loading-status"></div>
           <div class="wf-error-banner hidden" id="wf-error-banner" role="alert"></div>
           <div id="wf-form-inner"></div>
         </div>
@@ -60,6 +64,8 @@ export function createLayout(container) {
   const ringNum = root.querySelector('#wf-ring-num');
   const ring = root.querySelector('.wf-ring');
   const errorBanner = root.querySelector('#wf-error-banner');
+  const loadingBar = root.querySelector('#wf-loading-bar');
+  const loadingStatus = root.querySelector('#wf-loading-status');
 
   function setContent(el) {
     formInner.innerHTML = '';
@@ -90,11 +96,33 @@ export function createLayout(container) {
     errorBanner.classList.remove('hidden');
   }
 
+  function setLoading(active, message = '') {
+    if (active) {
+      loadingBar.classList.remove('hidden');
+      loadingBar.setAttribute('aria-busy', 'true');
+      formInner.classList.add('wf-loading-active');
+      if (message) {
+        loadingStatus.textContent = message;
+        loadingStatus.classList.remove('hidden');
+      } else {
+        loadingStatus.textContent = '';
+        loadingStatus.classList.add('hidden');
+      }
+    } else {
+      loadingBar.classList.add('hidden');
+      loadingBar.setAttribute('aria-busy', 'false');
+      formInner.classList.remove('wf-loading-active');
+      loadingStatus.classList.add('hidden');
+      loadingStatus.textContent = '';
+    }
+  }
+
   return {
     root,
     setContent,
     updateProgress,
     showError,
+    setLoading,
     renderContent: setContent,
   };
 }

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;
+  }
+}