@smileid/web-components 11.4.4 → 11.5.0

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

@@ -6,6 +6,7 @@ import type { FunctionComponent } from 'preact';
 import { getBoolProp } from '../../../../utils/props';
 import { translate, translateHtml } from '../../../../domain/localisation';
 import SmartSelfieCapture from '../smartselfie-capture/SmartSelfieCapture';
+import EnhancedSmartSelfieCapture from '../enhanced-smartselfie-capture/EnhancedSmartSelfieCapture';
 // Legacy web component fallback (used when Mediapipe isn't available)
 import '../selfie-capture/SelfieCapture';
 // Mediapipe loader/manager used by SmartSelfieCapture
@@ -40,6 +41,8 @@ interface Props {
   'show-agent-mode-for-tests'?: string | boolean;
   'hide-attribution'?: string | boolean;
   'disable-image-tests'?: string | boolean;
+  'use-strict-mode'?: string | boolean;
+  'show-back-on-guidelines'?: string | boolean;
   key?: string;
   'start-countdown'?: string | boolean;
   hidden?: string | boolean;
@@ -60,6 +63,11 @@ const DEFAULT_WAIT_MS = 20 * 1000;
 // 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;
+// Cap user-initiated retries from the failure screen. Each tap resets the
+// per-attempt counter (granting another `MAX_MEDIAPIPE_INIT_ATTEMPTS` round of
+// internal retries), so without this cap a frustrated or malicious user could
+// hammer Retry indefinitely and generate unbounded requests to the model CDN.
+const MAX_USER_RETRIES = 3;
 
 // Wrapper component that decides whether to use the modern
 // SmartSelfieCapture (Mediapipe-based) or fallback to the legacy `selfie-capture`
@@ -68,6 +76,7 @@ const SelfieCaptureWrapper: FunctionComponent<Props> = ({
   timeout,
   'start-countdown': startCountdownProp = false,
   'allow-legacy-selfie-fallback': allowLegacySelfieFallbackProp = false,
+  'use-strict-mode': useStrictModeProp = false,
   hidden: hiddenProp = false,
   ...props
 }) => {
@@ -89,9 +98,23 @@ const SelfieCaptureWrapper: FunctionComponent<Props> = ({
     (window.navigator.userAgent.includes('Electron') &&
       (window as any).__Cypress);
 
+  // Test-only seam: the `isCypress` short-circuit below skips the whole
+  // MediaPipe load path (so most specs run fast against the legacy fallback).
+  // A spec that wants to exercise the real load/spinner/error/Retry path sets
+  // `window.__SMILE_ID_TEST_FORCE_MEDIAPIPE_LOAD__ = true` to opt out of that
+  // short-circuit. When the flag is unset, `skipMediapipeForTests === isCypress`,
+  // so production and existing-test behaviour are unchanged.
+  const forceMediapipeLoad = !!(window as any)
+    .__SMILE_ID_TEST_FORCE_MEDIAPIPE_LOAD__;
+  const skipMediapipeForTests = isCypress && !forceMediapipeLoad;
+
   const hidden = getBoolProp(hiddenProp);
   const startCountdown = getBoolProp(startCountdownProp);
-  const allowLegacySelfieFallback = getBoolProp(allowLegacySelfieFallbackProp);
+  const useStrictMode = getBoolProp(useStrictModeProp);
+  // Strict mode (Enhanced SmartSelfie) requires Mediapipe head-pose detection,
+  // so the legacy fallback is force-disabled regardless of the partner setting.
+  const allowLegacySelfieFallback =
+    !useStrictMode && getBoolProp(allowLegacySelfieFallbackProp);
 
   // Resolve how long we'll wait for Mediapipe before the hard deadline fires.
   // Precedence:
@@ -122,11 +145,37 @@ const SelfieCaptureWrapper: FunctionComponent<Props> = ({
   // - initialSessionCompleted: set when the legacy component emits publish/cancel/close
   // - mediapipeLoading: true while attempting to load mediapipe
   // - usingSelfieCapture: whether we've mounted the legacy `selfie-capture` element
-  const [mediapipeReady, setMediapipeReady] = useState(false);
-  const [loadingProgress, setLoadingProgress] = useState(isCypress ? 100 : 0);
-  const [loadDeadlineExceeded, setLoadDeadlineExceeded] = useState(isCypress);
+  // If MediaPipe already loaded earlier in this session (e.g. we're remounting
+  // after returning from document capture), reuse the cached singleton instance
+  // immediately instead of showing the loading spinner again. The model and
+  // WASM are already in memory, so no network call is needed.
+  const mediapipeAlreadyLoaded = !!(
+    window.__smileIdentityMediapipe?.loaded &&
+    window.__smileIdentityMediapipe?.instance
+  );
+
+  const [mediapipeReady, setMediapipeReady] = useState(mediapipeAlreadyLoaded);
+  const [loadingProgress, setLoadingProgress] = useState(
+    skipMediapipeForTests || mediapipeAlreadyLoaded ? 100 : 0,
+  );
+  const [loadDeadlineExceeded, setLoadDeadlineExceeded] = useState(
+    skipMediapipeForTests,
+  );
   const [initialSessionCompleted, setInitialSessionCompleted] = useState(false);
   const [mediapipeLoading, setMediapipeLoading] = useState(false);
+  // Concurrency guard for the load effect. Kept in a ref — NOT in
+  // `mediapipeLoading` state — so the effect's guard does not depend on a value
+  // the effect itself sets. If it did (as it used to), calling
+  // `setMediapipeLoading(true)` would re-run the effect, whose cleanup flips
+  // `cancelled` true, and a slow `getMediapipeInstance()` would then resolve
+  // into a cancelled closure — never calling `setMediapipeReady(true)`. That
+  // left the UI stuck on the loading spinner even though MediaPipe loaded
+  // successfully (intermittent: only when the load lost the race to the
+  // re-render).
+  const mediapipeLoadingRef = useRef(false);
+  // Bumped to re-trigger the load effect for a bounded retry after a transient
+  // failure (replaces re-using `mediapipeLoading` as the re-trigger signal).
+  const [mediapipeRetryTick, setMediapipeRetryTick] = useState(0);
   // `unsupportedEnvironment` is a permanent, one-shot signal: we know
   // MediaPipe cannot run here, so stop trying.
   const [unsupportedEnvironment, setUnsupportedEnvironment] = useState(false);
@@ -137,6 +186,9 @@ const SelfieCaptureWrapper: FunctionComponent<Props> = ({
   // Dedup flag so we only report a given init failure to Sentry once per
   // wrapper instance, even if we end up retrying. Ref for the same reason.
   const mediapipeInitReportedRef = useRef(false);
+  // User-initiated Retry presses are also bounded — see `MAX_USER_RETRIES`.
+  const userRetryCountRef = useRef(0);
+  const [retriesExhausted, setRetriesExhausted] = useState(false);
   const [usingSelfieCapture, setUsingSelfieCapture] = useState(false);
 
   // Attempt to load Mediapipe (with a small bounded retry budget). If
@@ -147,27 +199,33 @@ const SelfieCaptureWrapper: FunctionComponent<Props> = ({
   useEffect(() => {
     if (
       mediapipeReady ||
-      mediapipeLoading ||
+      mediapipeLoadingRef.current ||
       unsupportedEnvironment ||
       mediapipeInitAttemptsRef.current >= MAX_MEDIAPIPE_INIT_ATTEMPTS ||
-      isCypress
+      skipMediapipeForTests
     )
       return undefined;
 
     let cancelled = false;
     let retryTimeoutId: ReturnType<typeof setTimeout> | null = null;
 
+    // Mark loading via the ref (effect guard) and the state (UI). The state is
+    // intentionally NOT in this effect's deps — see `mediapipeLoadingRef`.
+    mediapipeLoadingRef.current = true;
+    setMediapipeLoading(true);
+
     const loadMediapipe = async () => {
-      setMediapipeLoading(true);
       const attemptNumber = mediapipeInitAttemptsRef.current + 1;
       mediapipeInitAttemptsRef.current = attemptNumber;
       try {
         await getMediapipeInstance();
         if (cancelled) return;
+        mediapipeLoadingRef.current = false;
         setMediapipeReady(true);
         setMediapipeLoading(false);
       } catch (error) {
         if (cancelled) return;
+        mediapipeLoadingRef.current = false;
         // Loading failed; we'll fall back to the legacy selfie-capture component
         // after the loadingProgress reaches 100% (or sooner for definitively
         // unsupported environments — see below).
@@ -215,6 +273,9 @@ const SelfieCaptureWrapper: FunctionComponent<Props> = ({
           retryTimeoutId = null;
           if (cancelled) return;
           setMediapipeLoading(false);
+          // Re-trigger the effect for the next attempt via a dedicated counter
+          // rather than toggling `mediapipeLoading` (which is no longer a dep).
+          setMediapipeRetryTick((tick) => tick + 1);
         }, backoffMs);
       }
     };
@@ -223,11 +284,14 @@ const SelfieCaptureWrapper: FunctionComponent<Props> = ({
 
     return () => {
       cancelled = true;
+      mediapipeLoadingRef.current = false;
       if (retryTimeoutId !== null) {
         clearTimeout(retryTimeoutId);
       }
     };
-  }, [mediapipeReady, mediapipeLoading, unsupportedEnvironment]);
+    // `mediapipeLoading` is deliberately excluded: it is set inside this effect,
+    // so depending on it would re-run the effect and cancel the in-flight load.
+  }, [mediapipeReady, unsupportedEnvironment, mediapipeRetryTick]);
 
   // Cosmetic loading progress: ticks 0→100 over `loadingTime` so the UI can
   // show "slow connection" copy past the SLOW_CONNECTION_THRESHOLD. This is
@@ -249,14 +313,21 @@ const SelfieCaptureWrapper: FunctionComponent<Props> = ({
     return () => {
       clearInterval(timer);
     };
-  }, [hidden, startCountdown, loadingTime, mediapipeReady]);
+    // `mediapipeRetryTick` restarts the cosmetic progress when the user taps
+    // Retry (which resets `loadingProgress` to 0).
+  }, [hidden, startCountdown, loadingTime, mediapipeReady, mediapipeRetryTick]);
 
   // Hard deadline: a single setTimeout that flips `loadDeadlineExceeded`
   // exactly once. This is the signal the render path uses to commit to the
   // fallback. Skipped when hidden, when Mediapipe is already ready, or under
   // Cypress (where the flag is pre-seeded to true).
   useEffect(() => {
-    if (hidden || mediapipeReady || loadDeadlineExceeded || isCypress)
+    if (
+      hidden ||
+      mediapipeReady ||
+      loadDeadlineExceeded ||
+      skipMediapipeForTests
+    )
       return undefined;
 
     const id = setTimeout(() => {
@@ -264,7 +335,13 @@ const SelfieCaptureWrapper: FunctionComponent<Props> = ({
     }, loadingTime);
 
     return () => clearTimeout(id);
-  }, [hidden, mediapipeReady, loadDeadlineExceeded, loadingTime, isCypress]);
+  }, [
+    hidden,
+    mediapipeReady,
+    loadDeadlineExceeded,
+    loadingTime,
+    skipMediapipeForTests,
+  ]);
 
   // Latch the legacy fallback decision in an effect rather than during
   // render. Effects only run after commit, so by the time this runs, any
@@ -274,7 +351,8 @@ const SelfieCaptureWrapper: FunctionComponent<Props> = ({
   useEffect(() => {
     if (hidden || usingSelfieCapture || mediapipeReady) return;
     if (!loadDeadlineExceeded) return;
-    const legacyFallbackAllowed = allowLegacySelfieFallback || isCypress;
+    const legacyFallbackAllowed =
+      allowLegacySelfieFallback || skipMediapipeForTests;
     if (!legacyFallbackAllowed) return;
     setUsingSelfieCapture(true);
   }, [
@@ -283,7 +361,7 @@ const SelfieCaptureWrapper: FunctionComponent<Props> = ({
     mediapipeReady,
     loadDeadlineExceeded,
     allowLegacySelfieFallback,
-    isCypress,
+    skipMediapipeForTests,
   ]);
 
   useEffect(() => {
@@ -367,10 +445,45 @@ const SelfieCaptureWrapper: FunctionComponent<Props> = ({
     );
   }, [usingSelfieCapture, hidden, mediapipeLoading]);
 
+  // Retry from the failure screen: clear the give-up state and re-arm the load
+  // effect, deadline, and cosmetic progress so we make a fresh attempt. We reset
+  // `unsupportedEnvironment` so a genuinely unsupported device fails fast again
+  // (rather than spinning for the full deadline) instead of being permanently
+  // latched off. User taps are capped by `MAX_USER_RETRIES` so a frustrated or
+  // malicious user can't hammer Retry indefinitely and generate unbounded
+  // requests to the model CDN.
+  const handleRetry = () => {
+    if (userRetryCountRef.current >= MAX_USER_RETRIES) {
+      setRetriesExhausted(true);
+      return;
+    }
+    userRetryCountRef.current += 1;
+    mediapipeInitAttemptsRef.current = 0;
+    mediapipeInitReportedRef.current = false;
+    mediapipeLoadingRef.current = false;
+    setUnsupportedEnvironment(false);
+    setLoadDeadlineExceeded(false);
+    setLoadingProgress(0);
+    setMediapipeRetryTick((tick) => tick + 1);
+  };
+
   if (hidden) {
     return null;
   }
 
+  // Strict mode (Enhanced SmartSelfie) owns its own loading UX. Mount it
+  // immediately — the guidelines screen doesn't need Mediapipe, and by the
+  // time the user reaches the capture screen the background load started by
+  // `useFaceCapture.initializeFaceLandmarker()` will normally have resolved.
+  if (useStrictMode) {
+    return (
+      <>
+        <style>{`:host { display: block; height: 100%; }`}</style>
+        <EnhancedSmartSelfieCapture {...(props as any)} />
+      </>
+    );
+  }
+
   // on retakes, prefer SmartSelfieCapture if Mediapipe is ready
   if (initialSessionCompleted && mediapipeReady && !usingSelfieCapture) {
     return <SmartSelfieCapture {...props} />;
@@ -427,14 +540,45 @@ const SelfieCaptureWrapper: FunctionComponent<Props> = ({
     );
   }
 
-  // Hard deadline elapsed and legacy fallback isn't allowed: show the
-  // connection error.
-  if (loadDeadlineExceeded && !(allowLegacySelfieFallback || isCypress)) {
+  // Hard deadline elapsed and legacy fallback isn't allowed: show an actionable
+  // error. The network is usually fine here (the hold-up is on-device setup), so
+  // only blame the connection when the browser actually reports being offline —
+  // otherwise frame it as a setup problem. Always offer a Retry control.
+  if (
+    loadDeadlineExceeded &&
+    !(allowLegacySelfieFallback || skipMediapipeForTests)
+  ) {
+    const isOffline =
+      typeof navigator !== 'undefined' && navigator.onLine === false;
+    const errorKey = isOffline
+      ? 'selfie.capture.loading.offlineError'
+      : 'selfie.capture.loading.setupError';
+    const themeColor = (props as Record<string, string>)['theme-color'];
+
     return (
       <div style={{ textAlign: 'center', marginTop: '20%', padding: '0 20px' }}>
         <p style={{ fontSize: '1.2rem', color: '#333' }}>
-          {translate('selfie.capture.loading.connectionError')}
+          {translate(errorKey)}
         </p>
+        <button
+          type="button"
+          onClick={handleRetry}
+          disabled={retriesExhausted}
+          style={{
+            marginTop: '16px',
+            padding: '0.75rem 1.5rem',
+            borderRadius: '2.5rem',
+            border: 'none',
+            backgroundColor: themeColor || '#001096',
+            color: '#fff',
+            fontSize: '1rem',
+            fontWeight: 600,
+            cursor: retriesExhausted ? 'not-allowed' : 'pointer',
+            opacity: retriesExhausted ? 0.6 : 1,
+          }}
+        >
+          {translate('selfie.capture.loading.retry')}
+        </button>
       </div>
     );
   }
@@ -490,6 +634,8 @@ if (!customElements.get('selfie-capture-wrapper')) {
       'show-agent-mode-for-tests',
       'hide-attribution',
       'disable-image-tests',
+      'use-strict-mode',
+      'show-back-on-guidelines',
       'key',
       'start-countdown',
       'hidden',

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

@@ -237,11 +237,11 @@ const SmartSelfieCapture: FunctionComponent<Props> = ({
           font-family: "DM Sans", sans-serif;
           cursor: pointer;
         }
-        
+
         button.btn-primary:hover {
           background-color: #2d2b2a;
         }
-          
+
         button.btn-primary:disabled {
           background-color: #666;
           cursor: not-allowed;

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

@@ -336,6 +336,17 @@ export const useFaceCapture = ({
             }, 0);
           }
         }
+
+        // Before the smile zone, resume automatically when face returns to a
+        // valid position — no smile is needed yet.
+        if (
+          isPaused.value &&
+          isCapturing.value &&
+          capturesTaken.value < smileCheckpoint.value &&
+          resumeCaptureRef.current
+        ) {
+          resumeCaptureRef.current();
+        }
       } else {
         // No face detected - reset values
         currentSmileScore.value = 0;
@@ -414,9 +425,7 @@ export const useFaceCapture = ({
       };
 
       window.dispatchEvent(
-        new CustomEvent('selfie-capture.publish', {
-          detail: eventDetail,
-        }),
+        new CustomEvent('selfie-capture.publish', { detail: eventDetail }),
       );
 
       hasFinishedCapture.value = true;
@@ -515,10 +524,9 @@ export const useFaceCapture = ({
     smartCameraWeb?.dispatchEvent(
       new CustomEvent('metadata.selfie-origin', {
         detail: {
-          imageOrigin: {
-            environment: 'back_camera',
-            user: 'front_camera',
-          }[getFacingMode()],
+          imageOrigin: { environment: 'back_camera', user: 'front_camera' }[
+            getFacingMode()
+          ],
         },
       }),
     );

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

@@ -1,8 +1,8 @@
-import { DrawingUtils, FaceLandmarker } from '@mediapipe/tasks-vision';
-
 /**
  * Create a cropped square canvas from video for face detection
  */
+import { DrawingUtils, FaceLandmarker } from '@mediapipe/tasks-vision';
+
 export const createCroppedVideoFrame = (
   videoElement: HTMLVideoElement,
 ): HTMLCanvasElement | null => {
@@ -51,16 +51,14 @@ export const drawFaceMesh = (
   const canvasHeight = canvas.height;
 
   ctx.clearRect(0, 0, canvasWidth, canvasHeight);
-  const drawingUtils = new DrawingUtils(ctx);
 
-  // use this if scaling is needed
-  // const scaleFactor = Math.sqrt(canvasWidth * canvasHeight) / 500;
+  const drawingUtils = new DrawingUtils(ctx);
 
   landmarks.forEach((landmark) => {
     if (!landmark || landmark.length === 0) return;
 
     const outlineColor = 'rgba(162, 155, 254,0.4)';
-    const lineWidth = 2; // Math.max(1, scaleFactor * 2);
+    const lineWidth = 2;
     ctx.strokeStyle = 'rgba(255, 255, 255, 0.6)';
     ctx.lineWidth = lineWidth;
     ctx.lineCap = 'round';

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

@@ -122,6 +122,62 @@ export class UnsupportedMediapipeEnvironmentError extends Error {
   }
 }
 
+/**
+ * @description Thrown when `FaceLandmarker.createFromOptions` does not settle
+ * within {@link MEDIAPIPE_INIT_TIMEOUT_MS}. The WASM and model assets download
+ * over the network, but the subsequent WASM compile + GPU/CPU graph
+ * initialization runs on-device and can stall indefinitely on some drivers.
+ * Without a timeout the cached `loading` promise never resolves nor rejects,
+ * which (a) keeps the loading UI spinning until the wrapper's hard deadline and
+ * (b) poisons the singleton so retries/remounts await the same stuck promise.
+ * Treated as a transient failure by callers so the bounded retry can re-run.
+ */
+export class MediapipeInitTimeoutError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'MediapipeInitTimeoutError';
+  }
+}
+
+// Last-resort hang guard for `createFromOptions`. This call also downloads the
+// ~3MB model, so the budget must cover a slow/uncached fetch as well as the
+// on-device init — hence it is deliberately generous. It exists only so a truly
+// wedged init eventually rejects (letting the wrapper's bounded retry / hard
+// deadline take over) rather than hanging forever; it is NOT used to decide the
+// GPU→CPU fallback (that keys off real init errors — see getMediapipeInstance).
+const MEDIAPIPE_INIT_TIMEOUT_MS = 45000;
+
+/**
+ * @description Races a promise against a timeout. On timeout, rejects with a
+ * {@link MediapipeInitTimeoutError}. The underlying promise is not (and cannot
+ * be) aborted — we just stop awaiting it so callers can recover.
+ * @param {Promise<T>} promise The work to bound.
+ * @param {number} ms Timeout in milliseconds.
+ * @param {string} message Message for the timeout error.
+ * @returns {Promise<T>} Resolves/rejects with the promise, or rejects on timeout.
+ */
+const withTimeout = <T>(
+  promise: Promise<T>,
+  ms: number,
+  message: string,
+): Promise<T> =>
+  new Promise<T>((resolve, reject) => {
+    const timeoutId = setTimeout(() => {
+      reject(new MediapipeInitTimeoutError(message));
+    }, ms);
+
+    promise.then(
+      (value) => {
+        clearTimeout(timeoutId);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timeoutId);
+        reject(error);
+      },
+    );
+  });
+
 /**
  * @description Reads system architecture hints from User-Agent Client Hints.
  * @returns {Promise<string | null>} Lower-cased hint string or null when hints are unavailable.
@@ -207,6 +263,28 @@ const hasFP16Support = () => {
   return !!(hasHalfFloatExt && hasColorBufferHalfFloat && hasHalfFloatLinear);
 };
 
+/**
+ * @description Creates a FaceLandmarker with the given compute delegate.
+ * Extracted so the init can be retried with a different delegate without
+ * duplicating the options.
+ * @param {Awaited<ReturnType<typeof FilesetResolver.forVisionTasks>>} vision Resolved WASM fileset.
+ * @param {'CPU' | 'GPU'} delegate Compute delegate to use.
+ * @returns {Promise<FaceLandmarker>} The created FaceLandmarker.
+ */
+const createLandmarker = (
+  vision: Awaited<ReturnType<typeof FilesetResolver.forVisionTasks>>,
+  delegate: 'CPU' | 'GPU',
+): Promise<FaceLandmarker> =>
+  FaceLandmarker.createFromOptions(vision, {
+    baseOptions: {
+      modelAssetPath: `https://web-models.smileidentity.com/face_landmarker/face_landmarker.task`,
+      delegate,
+    },
+    outputFaceBlendshapes: true,
+    runningMode: 'VIDEO',
+    numFaces: 2,
+  });
+
 export const getMediapipeInstance = async (): Promise<FaceLandmarker> => {
   if (!window.__smileIdentityMediapipe) {
     window.__smileIdentityMediapipe = {
@@ -249,15 +327,69 @@ export const getMediapipeInstance = async (): Promise<FaceLandmarker> => {
       const delegate =
         gpuDelegate === 'CPU' || !hasFP16Support() ? 'CPU' : 'GPU';
 
-      const faceLandmarker = await FaceLandmarker.createFromOptions(vision, {
-        baseOptions: {
-          modelAssetPath: `https://web-models.smileidentity.com/face_landmarker/face_landmarker.task`,
-          delegate,
-        },
-        outputFaceBlendshapes: true,
-        runningMode: 'VIDEO',
-        numFaces: 2,
-      });
+      // A GPU-delegate init can throw on some drivers (WebGL context/shader
+      // failures) even though the model already downloaded; on a genuine GPU
+      // *error* we retry once on CPU before giving up. We deliberately do NOT
+      // fall back on a timeout: the timeout also covers the model download, so
+      // a slow fetch could trip it while a healthy GPU init is still in
+      // progress — abandoning it to start a redundant CPU init only makes
+      // things worse. A timeout therefore propagates as a transient failure for
+      // the wrapper's bounded retry / hard deadline to handle.
+      //
+      // Orphan handling: when `withTimeout` fires, the underlying
+      // `createLandmarker` promise is still in flight (it cannot be aborted).
+      // If it eventually resolves, the resulting `FaceLandmarker` would leak a
+      // GPU/WebGL context, so we attach a best-effort `.close()` cleanup to the
+      // original promise reference for both the GPU and CPU init paths.
+      const closeOrphan = (orphan: FaceLandmarker) => {
+        try {
+          orphan.close();
+        } catch {
+          /* best effort */
+        }
+      };
+
+      let faceLandmarker: FaceLandmarker;
+      const initPromise = createLandmarker(vision, delegate);
+      try {
+        faceLandmarker = await withTimeout(
+          initPromise,
+          MEDIAPIPE_INIT_TIMEOUT_MS,
+          `MediaPipe initialization timed out after ${MEDIAPIPE_INIT_TIMEOUT_MS}ms (delegate: ${delegate}).`,
+        );
+      } catch (error) {
+        const isTimeout = error instanceof MediapipeInitTimeoutError;
+        if (isTimeout) {
+          // Stop awaiting the in-flight init, but if it eventually resolves,
+          // close the orphaned instance to avoid leaking a GPU/WebGL context.
+          initPromise.then(closeOrphan, () => {
+            /* already failed; nothing to clean up */
+          });
+        }
+        if (delegate === 'GPU' && !isTimeout) {
+          console.warn(
+            '[SmileID] GPU MediaPipe init failed; retrying with CPU delegate.',
+            error,
+          );
+          const cpuInitPromise = createLandmarker(vision, 'CPU');
+          try {
+            faceLandmarker = await withTimeout(
+              cpuInitPromise,
+              MEDIAPIPE_INIT_TIMEOUT_MS,
+              `MediaPipe CPU initialization timed out after ${MEDIAPIPE_INIT_TIMEOUT_MS}ms.`,
+            );
+          } catch (cpuError) {
+            if (cpuError instanceof MediapipeInitTimeoutError) {
+              cpuInitPromise.then(closeOrphan, () => {
+                /* already failed; nothing to clean up */
+              });
+            }
+            throw cpuError;
+          }
+        } else {
+          throw error;
+        }
+      }
 
       mediapipeGlobal.instance = faceLandmarker;
       mediapipeGlobal.loaded = true;
@@ -265,6 +397,8 @@ export const getMediapipeInstance = async (): Promise<FaceLandmarker> => {
 
       return faceLandmarker;
     } catch (error) {
+      // Always clear the poisoned promise so the wrapper's bounded retry — and
+      // any later remount — can re-attempt instead of awaiting a dead promise.
       mediapipeGlobal.loading = null;
       throw error;
     }
@@ -277,4 +411,6 @@ export const __testUtils = {
   matchesExcludedGpu,
   getDelegateFromGpuDetection,
   supportsWasmReftypes,
+  withTimeout,
+  MEDIAPIPE_INIT_TIMEOUT_MS,
 };

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

@@ -1,6 +1,6 @@
 {
   "name": "@smileid/signature-pad",
-  "version": "11.4.4",
+  "version": "11.5.0",
   "private": true,
   "exports": {
     ".": "./index.js"