@smileid/web-components 11.4.1 → 11.4.3

package/dist/types/main.d.ts

@@ -38,6 +38,8 @@ declare class ComboboxRoot extends HTMLElement {
 declare class ComboboxTrigger extends HTMLElement {
     handleKeyUp(event: any): void;
     handleKeyDown(event: any): void;
+    handleInput(event: any): void;
+    handleChange(event: any): void;
     handleSelection(event: any): void;
     toggleExpansionState(): void;
     get type(): string;
@@ -87,13 +89,13 @@ export declare class DocumentCaptureScreens extends HTMLElement {
     setUpEventListeners(): void;
     _publishSelectedImages(): void;
     get hideInstructions(): boolean;
-    get autoCapture(): boolean;
     get hideBackOfId(): boolean;
     get showNavigation(): "" | "show-navigation";
     get title(): string;
     get documentCaptureModes(): string;
     get documentType(): string;
     get hideAttribution(): "" | "hide-attribution";
+    get newInstructions(): boolean;
     get themeColor(): string;
     handleBackEvents(): void;
     handleCloseEvents(): void;
@@ -329,6 +331,7 @@ export declare class SmartCameraWeb extends HTMLElement {
     get isPortraitCaptureView(): boolean;
     get hideInstructions(): "" | "hide-instructions";
     get hideBackOfId(): "" | "hide-back-of-id";
+    get newInstructions(): "" | "new-instructions";
     get showNavigation(): "" | "show-navigation";
     get hideBackToHost(): "" | "hide-back";
     get allowAgentMode(): string;

package/lib/components/selfie/src/selfie-capture-wrapper/SelfieCaptureWrapper.tsx

@@ -9,7 +9,25 @@ import SmartSelfieCapture from '../smartselfie-capture/SmartSelfieCapture';
 // Legacy web component fallback (used when Mediapipe isn't available)
 import '../selfie-capture/SelfieCapture';
 // Mediapipe loader/manager used by SmartSelfieCapture
-import { getMediapipeInstance } from '../smartselfie-capture/utils/mediapipeManager';
+import {
+  getMediapipeInstance,
+  UnsupportedMediapipeEnvironmentError,
+} from '../smartselfie-capture/utils/mediapipeManager';
+
+// Minimal typing for the optional Sentry SDK that host pages may expose on
+// `window`. We only depend on `captureException`, so keep the surface tight.
+// Sentry tag values are expected to be strings, so the type enforces that.
+type SentryTags = Record<string, string>;
+declare global {
+  interface Window {
+    Sentry?: {
+      captureException: (
+        error: unknown,
+        context?: { tags?: SentryTags },
+      ) => void;
+    };
+  }
+}
 
 interface Props {
   timeout?: number;
@@ -29,6 +47,12 @@ interface Props {
 
 const DEFAULT_MEDIAPIPE_WAIT_MS = 90 * 1000; // For when legacy fallback is NOT allowed, we wait the full 90s for mediapipe to load before showing an error.
 const DEFAULT_WAIT_MS = 20 * 1000; // default for when legacy fallback is allowed we wait for 20s
+// Cap retries on transient init failures so we don't spin forever, while still
+// allowing recovery from short-lived issues (e.g. CDN hiccups while the
+// wrapper is preloading in a hidden state). Retries are spaced with
+// exponential backoff (base * 2^(attempt-1)) so we don't hammer the CDN.
+const MAX_MEDIAPIPE_INIT_ATTEMPTS = 3;
+const MEDIAPIPE_RETRY_BASE_DELAY_MS = 500;
 
 // Wrapper component that decides whether to use the modern
 // SmartSelfieCapture (Mediapipe-based) or fallback to the legacy `selfie-capture`
@@ -73,29 +97,110 @@ const SelfieCaptureWrapper: FunctionComponent<Props> = ({
   const [loadingProgress, setLoadingProgress] = useState(isCypress ? 100 : 0);
   const [initialSessionCompleted, setInitialSessionCompleted] = useState(false);
   const [mediapipeLoading, setMediapipeLoading] = useState(false);
+  // `unsupportedEnvironment` is a permanent, one-shot signal: we know
+  // MediaPipe cannot run here, so stop trying.
+  const [unsupportedEnvironment, setUnsupportedEnvironment] = useState(false);
+  // Bounded retry counter for transient init failures.
+  const [mediapipeInitAttempts, setMediapipeInitAttempts] = useState(0);
+  // Dedup flag so we only report a given init failure to Sentry once per
+  // wrapper instance, even if we end up retrying.
+  const [mediapipeInitReported, setMediapipeInitReported] = useState(false);
   const [usingSelfieCapture, setUsingSelfieCapture] = useState(false);
 
-  // Attempt to load Mediapipe (once). If Mediapipe is already ready, loading,
-  // or running under Cypress, skip the attempt. This side-effect flips
-  // mediapipeReady/mediapipeLoading flags which control which component is used.
+  // Attempt to load Mediapipe (with a small bounded retry budget). If
+  // Mediapipe is already ready, currently loading, the environment is
+  // definitively unsupported, we've exhausted our retry budget, or we're
+  // running under Cypress, skip the attempt. On transient failure we wait
+  // (exponential backoff) before allowing the effect to re-run.
   useEffect(() => {
-    if (mediapipeReady || mediapipeLoading || isCypress) return;
+    if (
+      mediapipeReady ||
+      mediapipeLoading ||
+      unsupportedEnvironment ||
+      mediapipeInitAttempts >= MAX_MEDIAPIPE_INIT_ATTEMPTS ||
+      isCypress
+    )
+      return undefined;
+
+    let cancelled = false;
+    let retryTimeoutId: ReturnType<typeof setTimeout> | null = null;
 
     const loadMediapipe = async () => {
       setMediapipeLoading(true);
+      const attemptNumber = mediapipeInitAttempts + 1;
+      setMediapipeInitAttempts(attemptNumber);
       try {
         await getMediapipeInstance();
+        if (cancelled) return;
         setMediapipeReady(true);
+        setMediapipeLoading(false);
       } catch (error) {
+        if (cancelled) return;
         // Loading failed; we'll fall back to the legacy selfie-capture component
-        // after the loadingProgress reaches 100%.
+        // after the loadingProgress reaches 100% (or sooner for definitively
+        // unsupported environments — see below).
         console.error('Failed to load Mediapipe:', error);
+        const isUnsupportedEnvironment =
+          error instanceof UnsupportedMediapipeEnvironmentError;
+        // Report to Sentry (when the host page has exposed it on window) so we
+        // can observe how often users land on the fallback path and which
+        // environments are affected. Dedup so retries don't flood Sentry.
+        if (!mediapipeInitReported) {
+          setMediapipeInitReported(true);
+          window.Sentry?.captureException(error, {
+            tags: {
+              area: 'mediapipe_init',
+              mediapipe_unsupported_environment: isUnsupportedEnvironment
+                ? 'true'
+                : 'false',
+            },
+          });
+        }
+        // When the environment definitively cannot run MediaPipe (e.g. no
+        // WebAssembly reftypes support), there is no point retrying or keeping
+        // the user staring at the loading spinner for the full countdown —
+        // mark as unsupported and short-circuit to the fallback decision
+        // immediately.
+        if (isUnsupportedEnvironment) {
+          setUnsupportedEnvironment(true);
+          setLoadingProgress(100);
+          setMediapipeLoading(false);
+          return;
+        }
+        // Transient failure: wait with exponential backoff before allowing the
+        // effect to re-run by flipping mediapipeLoading back to false. If
+        // we've exhausted our retry budget, just release the loading flag so
+        // the countdown / fallback UI can proceed.
+        const hasRetriesLeft = attemptNumber < MAX_MEDIAPIPE_INIT_ATTEMPTS;
+        if (!hasRetriesLeft) {
+          setMediapipeLoading(false);
+          return;
+        }
+        const backoffMs =
+          MEDIAPIPE_RETRY_BASE_DELAY_MS * 2 ** (attemptNumber - 1);
+        retryTimeoutId = setTimeout(() => {
+          retryTimeoutId = null;
+          if (cancelled) return;
+          setMediapipeLoading(false);
+        }, backoffMs);
       }
-      setMediapipeLoading(false);
     };
 
     loadMediapipe();
-  }, [mediapipeReady, mediapipeLoading]);
+
+    return () => {
+      cancelled = true;
+      if (retryTimeoutId !== null) {
+        clearTimeout(retryTimeoutId);
+      }
+    };
+  }, [
+    mediapipeReady,
+    mediapipeLoading,
+    unsupportedEnvironment,
+    mediapipeInitAttempts,
+    mediapipeInitReported,
+  ]);
 
   // When using the loading countdown (startCountdown), increment the
   // visible loading progress. This is only used while mediapipe hasn't

package/lib/components/selfie/src/smartselfie-capture/SmartSelfieCapture.tsx

@@ -3,6 +3,7 @@ import register from 'preact-custom-element';
 import type { FunctionComponent } from 'preact';
 
 import { getBoolProp } from '../../../../utils/props';
+import { translate } from '../../../../domain/localisation';
 import { useFaceCapture, useCamera } from './hooks';
 import { CameraPreview } from './components/CameraPreview';
 import { AlertDisplay } from './components/AlertDisplay';
@@ -61,8 +62,8 @@ const SmartSelfieCapture: FunctionComponent<Props> = ({
     getFacingMode: () => camera.facingMode,
   });
 
-  useEffect(() => {
-    const initializeCamera = async () => {
+  const initializeCamera = async () => {
+    try {
       await camera.startCamera(initialFacingMode, (cameraName) => {
         const smartCameraWeb = document.querySelector('smart-camera-web');
         smartCameraWeb?.dispatchEvent(
@@ -71,15 +72,20 @@ const SmartSelfieCapture: FunctionComponent<Props> = ({
           }),
         );
       });
-      await camera.checkAgentSupport();
-      await faceCapture.initializeFaceLandmarker();
+    } catch {
+      // startCamera already set cameraError; surface UI and skip downstream init
+      return;
+    }
+    await camera.checkAgentSupport();
+    await faceCapture.initializeFaceLandmarker();
 
-      setTimeout(() => {
-        faceCapture.setupCanvas();
-        faceCapture.startDetectionLoop();
-      }, 500);
-    };
+    setTimeout(() => {
+      faceCapture.setupCanvas();
+      faceCapture.startDetectionLoop();
+    }, 500);
+  };
 
+  useEffect(() => {
     camera.registerCameraSwitchCallback(() => {
       try {
         faceCapture.resetFaceDetectionState();
@@ -142,39 +148,57 @@ const SmartSelfieCapture: FunctionComponent<Props> = ({
         <smileid-navigation ref={navigationRef} theme-color={themeColor} />
       )}
 
-      <CameraPreview
-        videoRef={camera.videoRef}
-        canvasRef={canvasRef}
-        facingMode={camera.facingMode}
-        progress={
-          faceCapture.capturesTaken.value > 0
-            ? faceCapture.capturesTaken.value / faceCapture.totalCaptures.value
-            : 0
-        }
-        interval={interval}
-        themeColor={themeColor}
-      />
-
-      <AlertDisplay alertTitle={faceCapture.alertTitle.value} />
-
-      {!faceCapture.isCapturing.value &&
-        !faceCapture.hasFinishedCapture.value && (
-          <CaptureControls
-            isCapturing={faceCapture.isCapturing.value}
-            hasFinishedCapture={faceCapture.hasFinishedCapture.value}
-            isReadyToCapture={faceCapture.isReadyToCapture.value}
-            captureButtonFallbackEnabled={
-              faceCapture.captureButtonFallbackEnabled.value
-            }
-            allowAgentMode={allowAgentMode}
-            agentSupported={camera.agentSupported}
-            showAgentModeForTests={showAgentModeForTests}
+      {camera.cameraError ? (
+        <div className="camera-error" role="alert">
+          <p>{camera.cameraError}</p>
+          <button
+            type="button"
+            className="btn-primary"
+            onClick={() => {
+              initializeCamera();
+            }}
+          >
+            {translate('camera.error.retry')}
+          </button>
+        </div>
+      ) : (
+        <>
+          <CameraPreview
+            videoRef={camera.videoRef}
+            canvasRef={canvasRef}
             facingMode={camera.facingMode}
+            progress={
+              faceCapture.capturesTaken.value > 0
+                ? faceCapture.capturesTaken.value /
+                  faceCapture.totalCaptures.value
+                : 0
+            }
+            interval={interval}
             themeColor={themeColor}
-            onStartCapture={faceCapture.startCapture}
-            onSwitchCamera={camera.switchCamera}
           />
-        )}
+
+          <AlertDisplay alertTitle={faceCapture.alertTitle.value} />
+
+          {!faceCapture.isCapturing.value &&
+            !faceCapture.hasFinishedCapture.value && (
+              <CaptureControls
+                isCapturing={faceCapture.isCapturing.value}
+                hasFinishedCapture={faceCapture.hasFinishedCapture.value}
+                isReadyToCapture={faceCapture.isReadyToCapture.value}
+                captureButtonFallbackEnabled={
+                  faceCapture.captureButtonFallbackEnabled.value
+                }
+                allowAgentMode={allowAgentMode}
+                agentSupported={camera.agentSupported}
+                showAgentModeForTests={showAgentModeForTests}
+                facingMode={camera.facingMode}
+                themeColor={themeColor}
+                onStartCapture={faceCapture.startCapture}
+                onSwitchCamera={camera.switchCamera}
+              />
+            )}
+        </>
+      )}
 
       {/* @ts-expect-error -- preact-custom-element doesn't have proper types for refs */}
       {!hideAttribution && <powered-by-smile-id />}
@@ -227,6 +251,15 @@ const SmartSelfieCapture: FunctionComponent<Props> = ({
           padding: 1rem;
           font-family: sans-serif;
         }
+
+        .camera-error {
+          margin-top: 1.5rem;
+          padding: 1rem 1.5rem;
+          color: #b00020;
+          text-align: center;
+          font-size: 1rem;
+          font-weight: 500;
+        }
       `}</style>
     </div>
   );

package/lib/components/selfie/src/smartselfie-capture/hooks/useCamera.ts

@@ -1,10 +1,12 @@
 import { useRef, useState, useEffect } from 'preact/hooks';
+import SmartCamera from '../../../../../domain/camera/src/SmartCamera';
 
 export const useCamera = (initialFacingMode: CameraFacingMode = 'user') => {
   const videoRef = useRef<HTMLVideoElement>(null);
   const streamRef = useRef<MediaStream | null>(null);
   const [facingMode, setFacingMode] = useState(initialFacingMode);
   const [agentSupported, setAgentSupported] = useState(false);
+  const [cameraError, setCameraError] = useState<string | null>(null);
   const onCameraSwitchCallbackRef = useRef<(() => void) | null>(null);
   const isSwitchingCameraRef = useRef(false);
   const timeoutIdsRef = useRef<Set<NodeJS.Timeout>>(new Set());
@@ -63,6 +65,7 @@ export const useCamera = (initialFacingMode: CameraFacingMode = 'user') => {
         video: { facingMode: targetFacingMode || facingMode },
       });
       streamRef.current = stream;
+      setCameraError(null);
 
       const track = stream.getVideoTracks()[0];
       const settings = track.getSettings();
@@ -94,9 +97,15 @@ export const useCamera = (initialFacingMode: CameraFacingMode = 'user') => {
       }
     } catch (error) {
       console.error('Failed to start camera:', error);
+      setCameraError(SmartCamera.handleCameraError(error as Error));
+      throw error;
     }
   };
 
+  const retryCamera = async () => {
+    await startCamera(facingMode);
+  };
+
   const switchCamera = async () => {
     const newFacingMode = facingMode === 'user' ? 'environment' : 'user';
     isSwitchingCameraRef.current = true;
@@ -118,6 +127,7 @@ export const useCamera = (initialFacingMode: CameraFacingMode = 'user') => {
         await startCamera(previousFacingMode);
       } catch (restoreError) {
         console.error('Failed to restore previous camera:', restoreError);
+        setCameraError(SmartCamera.handleCameraError(restoreError as Error));
       }
     }
   };
@@ -229,7 +239,9 @@ export const useCamera = (initialFacingMode: CameraFacingMode = 'user') => {
     streamRef,
     facingMode,
     agentSupported,
+    cameraError,
     startCamera,
+    retryCamera,
     switchCamera,
     checkAgentSupport,
     stopCamera,

package/lib/components/selfie/src/smartselfie-capture/utils/mediapipeManager.ts

@@ -67,10 +67,61 @@ declare global {
       instance: FaceLandmarker | null;
       loading: Promise<FaceLandmarker> | null;
       loaded: boolean;
+      supportsWasmReftypes?: boolean;
     };
   }
 }
 
+/**
+ * @description Detects whether the current runtime supports the WebAssembly
+ * reference-types proposal (the `externref` value type). MediaPipe Tasks
+ * Vision ships a .wasm that uses `externref`; on older engines (e.g. Chrome
+ * < 96, Safari < 15, Firefox < 79) `WebAssembly.instantiate` throws
+ * `CompileError: invalid value type 'externref'`. We probe support once with
+ * `WebAssembly.validate` against a tiny module whose only feature is an
+ * `externref`-typed global so callers can short-circuit and fall back to the
+ * legacy selfie capture flow instead of triggering an unhandled rejection.
+ * @returns {boolean} True if the runtime accepts reftypes / externref.
+ */
+const supportsWasmReftypes = (): boolean => {
+  if (typeof WebAssembly === 'undefined' || !WebAssembly.validate) {
+    return false;
+  }
+
+  try {
+    // Minimal module: magic + version + global section with one externref
+    // global (value type 0x6f) initialized to ref.null extern (0xd0 0x6f 0x0b).
+    const bytes = new Uint8Array([
+      0x00,
+      0x61,
+      0x73,
+      0x6d, // \0asm magic
+      0x01,
+      0x00,
+      0x00,
+      0x00, // version 1
+      0x06,
+      0x06,
+      0x01, // global section, 6 bytes, 1 global
+      0x6f,
+      0x00, // externref, immutable
+      0xd0,
+      0x6f,
+      0x0b, // ref.null extern; end
+    ]);
+    return WebAssembly.validate(bytes);
+  } catch {
+    return false;
+  }
+};
+
+export class UnsupportedMediapipeEnvironmentError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'UnsupportedMediapipeEnvironmentError';
+  }
+}
+
 /**
  * @description Reads system architecture hints from User-Agent Client Hints.
  * @returns {Promise<string | null>} Lower-cased hint string or null when hints are unavailable.
@@ -175,6 +226,19 @@ export const getMediapipeInstance = async (): Promise<FaceLandmarker> => {
     return mediapipeGlobal.loading;
   }
 
+  // Fail fast on engines that don't support WebAssembly reftypes/externref.
+  // The MediaPipe Tasks Vision .wasm uses externref globals; instantiating it
+  // on older browsers throws an unhandled `CompileError`. We detect once and
+  // cache the result so callers fall back to the legacy capture flow.
+  if (mediapipeGlobal.supportsWasmReftypes === undefined) {
+    mediapipeGlobal.supportsWasmReftypes = supportsWasmReftypes();
+  }
+  if (!mediapipeGlobal.supportsWasmReftypes) {
+    throw new UnsupportedMediapipeEnvironmentError(
+      'WebAssembly reference types (externref) are not supported in this browser; MediaPipe Tasks Vision cannot be loaded.',
+    );
+  }
+
   mediapipeGlobal.loading = (async () => {
     try {
       const vision = await FilesetResolver.forVisionTasks(
@@ -212,4 +276,5 @@ export const getMediapipeInstance = async (): Promise<FaceLandmarker> => {
 export const __testUtils = {
   matchesExcludedGpu,
   getDelegateFromGpuDetection,
+  supportsWasmReftypes,
 };

package/lib/components/signature-pad/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@smileid/signature-pad",
-  "version": "11.4.1",
-  "private": "true",
+  "version": "11.4.3",
+  "private": true,
   "exports": {
     ".": "./index.js"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smileid/web-components",
-  "version": "11.4.1",
+  "version": "11.4.3",
   "private": false,
   "main": "dist/esm/main.js",
   "module": "dist/esm/main.js",
@@ -76,6 +76,15 @@
   ],
   "type": "module",
   "author": "SmileID <support@usesmileid.com> (https://usesmileid.com)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/smileidentity/web-client.git",
+    "directory": "packages/web-components"
+  },
+  "bugs": {
+    "url": "https://github.com/smileidentity/web-client/issues"
+  },
+  "homepage": "https://github.com/smileidentity/web-client#readme",
   "dependencies": {
     "@lottiefiles/dotlottie-web": "^0.71.0",
     "@mediapipe/tasks-vision": "^0.10.22-rc.20250304",