@smileid/web-components 11.4.3 → 11.4.5

package/dist/types/main.d.ts

@@ -242,8 +242,10 @@ export declare class SelfieCaptureScreens extends HTMLElement {
     }[] | null | undefined;
     setUpEventListeners(): void;
     forceWrapperRemount(): Promise<any>;
+    restartSelfieCapture(): void;
     setActiveScreen(screen: any): void;
     setupSelfieWrapperEventListeners(): void;
+    _selfieWrapperPublishHandler: ((event: any) => Promise<void>) | undefined;
     _publishSelectedImages(): void;
     get hideInstructions(): boolean;
     get hideAttribution(): "" | "hide-attribution=\"\"";

package/lib/components/selfie/src/SelfieCaptureScreens.js

@@ -1,6 +1,7 @@
 import './selfie-capture-instructions';
 import './selfie-capture-review';
 import './selfie-capture-wrapper/index.ts';
+import { getMediapipeInstance } from './smartselfie-capture/utils/mediapipeManager.ts';
 import SmartCamera from '../../../domain/camera/src/SmartCamera';
 import styles from '../../../styles/src/styles';
 import packageJson from '../../../../package.json';
@@ -108,6 +109,37 @@ class SelfieCaptureScreens extends HTMLElement {
     }
 
     this.setUpEventListeners();
+
+    // Pre-warm MediaPipe as soon as the selfie flow starts so the heavy WASM +
+    // model download (and on-device init) happens while the user reads the
+    // instructions — not behind a blocking spinner on the capture screen. This
+    // is fire-and-forget and idempotent: getMediapipeInstance() caches a single
+    // in-flight promise / instance, so the wrapper (and any remount) reuses the
+    // same load instead of starting a new one. Errors are handled by the
+    // wrapper's own retry/fallback path, so swallow them here.
+    //
+    // Skipped under Cypress to match `SelfieCaptureWrapper`'s existing test
+    // seam (`skipMediapipeForTests`). Specs rely on the wrapper short-circuiting
+    // to the legacy `selfie-capture` fallback; pre-warming here would race with
+    // that seam and (intermittently) flip the wrapper into the SmartSelfie path
+    // by populating `window.__smileIdentityMediapipe` before the wrapper mounts.
+    //
+    // The parent check covers the embed Cypress context where this element runs
+    // inside an iframe and window.Cypress is only set on the parent frame.
+    const isCypress =
+      !!window.Cypress ||
+      (() => {
+        try {
+          return !!window.parent.Cypress;
+        } catch {
+          return false;
+        }
+      })() ||
+      (window.navigator.userAgent.includes('Electron') && window.__Cypress);
+    const forceMediapipeLoad = !!window.__SMILE_ID_TEST_FORCE_MEDIAPIPE_LOAD__;
+    if (!isCypress || forceMediapipeLoad) {
+      getMediapipeInstance().catch(() => {});
+    }
   }
 
   getAgentMode() {
@@ -230,6 +262,45 @@ class SelfieCaptureScreens extends HTMLElement {
     });
   }
 
+  // Return to a clean selfie capture screen. Used when navigating back from the
+  // document flow. Previously this was driven by toggling the `initial-screen`
+  // attribute on this element, which re-fired a full `connectedCallback()`
+  // rebuild every time (even when the value was unchanged). We now swap in a
+  // fresh `selfie-capture-wrapper` synchronously and navigate explicitly, so we
+  // land on a clean capture screen — not the stale review — without rebuilding
+  // the whole screen tree or depending on timers.
+  restartSelfieCapture() {
+    SmartCamera.stopMedia();
+
+    const container = this.querySelector('div');
+    const oldWrapper = this.selfieCapture;
+
+    if (oldWrapper && container) {
+      this._remountKey++;
+
+      const newWrapper = document.createElement('selfie-capture-wrapper');
+      Array.from(oldWrapper.attributes).forEach((attr) => {
+        newWrapper.setAttribute(attr.name, attr.value);
+      });
+      newWrapper.setAttribute('key', this._remountKey.toString());
+      newWrapper.setAttribute('start-countdown', 'false');
+      newWrapper.setAttribute('hidden', '');
+
+      const reviewElement = container.querySelector('selfie-capture-review');
+      oldWrapper.remove();
+      if (reviewElement) {
+        container.insertBefore(newWrapper, reviewElement);
+      } else {
+        container.appendChild(newWrapper);
+      }
+
+      this.selfieCapture = newWrapper;
+      this.setupSelfieWrapperEventListeners();
+    }
+
+    this.setActiveScreen(this.selfieCapture);
+  }
+
   // Override setActiveScreen to enable countdown when selfie-capture is active
   setActiveScreen(screen) {
     if (this.activeScreen === screen) {
@@ -256,6 +327,17 @@ class SelfieCaptureScreens extends HTMLElement {
         window.removeEventListener(event, handler);
       });
     }
+    // Also remove the previously-attached element-level publish handler so we
+    // don't accumulate duplicates across remounts (each call to
+    // setupSelfieWrapperEventListeners would otherwise add another listener,
+    // causing multiple transitions to review / multiple metadata events on
+    // navigating back from document capture).
+    if (this._selfieWrapperPublishHandler) {
+      this.removeEventListener(
+        'selfie-capture.publish',
+        this._selfieWrapperPublishHandler,
+      );
+    }
 
     // Create new event handlers
     const cancelledHandler = async () => {
@@ -313,6 +395,7 @@ class SelfieCaptureScreens extends HTMLElement {
 
     // Also listen for the publish event on the parent SelfieCaptureScreens element
     // in case smartselfie-capture dispatches it there
+    this._selfieWrapperPublishHandler = publishHandler;
     this.addEventListener('selfie-capture.publish', publishHandler);
   }
 

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

@@ -1,4 +1,4 @@
-import { useState, useEffect } from 'preact/hooks';
+import { useState, useEffect, useRef } from 'preact/hooks';
 import { IconLoader2 } from '@tabler/icons-preact';
 import register from 'preact-custom-element';
 import type { FunctionComponent } from 'preact';
@@ -30,7 +30,7 @@ declare global {
 }
 
 interface Props {
-  timeout?: number;
+  timeout?: string | number;
   interval?: number;
   duration?: number;
   'theme-color'?: string;
@@ -45,20 +45,32 @@ interface Props {
   hidden?: string | boolean;
 }
 
-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
+// Default deadlines for the Mediapipe load attempt. These are used when the
+// host did NOT provide an explicit `timeout` prop; an explicit `timeout`
+// always wins regardless of the legacy-fallback flag.
+//   - With legacy fallback allowed: 20s, so users on broken networks get a
+//     usable capture quickly.
+//   - Without legacy fallback: 90s, so we keep waiting before giving up to
+//     the error UI.
+const DEFAULT_MEDIAPIPE_WAIT_MS = 90 * 1000;
+const DEFAULT_WAIT_MS = 20 * 1000;
 // 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;
+// 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`
 // web component after a timeout (default 90 seconds).
 const SelfieCaptureWrapper: FunctionComponent<Props> = ({
-  timeout = DEFAULT_MEDIAPIPE_WAIT_MS,
+  timeout,
   'start-countdown': startCountdownProp = false,
   'allow-legacy-selfie-fallback': allowLegacySelfieFallbackProp = false,
   hidden: hiddenProp = false,
@@ -82,29 +94,93 @@ 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 loadingTime = allowLegacySelfieFallback ? DEFAULT_WAIT_MS : timeout;
+
+  // Resolve how long we'll wait for Mediapipe before the hard deadline fires.
+  // Precedence:
+  //   1. Explicit `timeout` prop (parsed defensively because web component
+  //      attributes arrive as strings).
+  //   2. With legacy fallback allowed: DEFAULT_WAIT_MS (20s).
+  //   3. Otherwise: DEFAULT_MEDIAPIPE_WAIT_MS (90s).
+  const parsedTimeout = typeof timeout === 'string' ? Number(timeout) : timeout;
+  const hasExplicitTimeout =
+    typeof parsedTimeout === 'number' &&
+    Number.isFinite(parsedTimeout) &&
+    parsedTimeout > 0;
+  const defaultLoadingTime = allowLegacySelfieFallback
+    ? DEFAULT_WAIT_MS
+    : DEFAULT_MEDIAPIPE_WAIT_MS;
+  const loadingTime = hasExplicitTimeout
+    ? (parsedTimeout as number)
+    : defaultLoadingTime;
 
   // Component state:
   // - mediapipeReady: whether the mediapipe instance has successfully loaded
-  // - loadingProgress: percentage used for the visible loading UI
+  // - loadingProgress: percentage used for the visible loading UI (cosmetic)
+  // - loadDeadlineExceeded: hard cap signal — once true, we stop waiting for
+  //   Mediapipe and commit to the legacy fallback (or error UI). Kept
+  //   separate from `loadingProgress` so the decision is driven by a single
+  //   setTimeout firing once, not by a 200ms ticking interval that can race
+  //   with the Mediapipe promise resolution.
   // - 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);
+  // 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);
-  // Bounded retry counter for transient init failures.
-  const [mediapipeInitAttempts, setMediapipeInitAttempts] = useState(0);
+  // Bounded retry counter for transient init failures. Stored in a ref so
+  // incrementing it does not trigger a re-render — it's only read inside the
+  // load effect.
+  const mediapipeInitAttemptsRef = useRef(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);
+  // 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
@@ -115,27 +191,33 @@ const SelfieCaptureWrapper: FunctionComponent<Props> = ({
   useEffect(() => {
     if (
       mediapipeReady ||
-      mediapipeLoading ||
+      mediapipeLoadingRef.current ||
       unsupportedEnvironment ||
-      mediapipeInitAttempts >= MAX_MEDIAPIPE_INIT_ATTEMPTS ||
-      isCypress
+      mediapipeInitAttemptsRef.current >= MAX_MEDIAPIPE_INIT_ATTEMPTS ||
+      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 = mediapipeInitAttempts + 1;
-      setMediapipeInitAttempts(attemptNumber);
+      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).
@@ -145,8 +227,8 @@ const SelfieCaptureWrapper: FunctionComponent<Props> = ({
         // 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);
+        if (!mediapipeInitReportedRef.current) {
+          mediapipeInitReportedRef.current = true;
           window.Sentry?.captureException(error, {
             tags: {
               area: 'mediapipe_init',
@@ -164,6 +246,7 @@ const SelfieCaptureWrapper: FunctionComponent<Props> = ({
         if (isUnsupportedEnvironment) {
           setUnsupportedEnvironment(true);
           setLoadingProgress(100);
+          setLoadDeadlineExceeded(true);
           setMediapipeLoading(false);
           return;
         }
@@ -182,6 +265,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);
       }
     };
@@ -190,35 +276,88 @@ const SelfieCaptureWrapper: FunctionComponent<Props> = ({
 
     return () => {
       cancelled = true;
+      mediapipeLoadingRef.current = false;
       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
-  // reported ready; once mediapipeReady becomes true we stop the timer.
+    // `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
+  // purely visual — it does NOT decide when we fall back. The decision is
+  // driven by `loadDeadlineExceeded` below.
   useEffect(() => {
     if (hidden || !startCountdown || mediapipeReady) return undefined;
 
     const timer = setInterval(() => {
-      setLoadingProgress((prev: number) => Math.min(prev + 1, 100));
+      setLoadingProgress((prev: number) => {
+        if (prev >= 100) {
+          clearInterval(timer);
+          return 100;
+        }
+        return prev + 1;
+      });
     }, loadingTime / 100);
 
     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 ||
+      skipMediapipeForTests
+    )
+      return undefined;
+
+    const id = setTimeout(() => {
+      setLoadDeadlineExceeded(true);
+    }, loadingTime);
+
+    return () => clearTimeout(id);
+  }, [
+    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
+  // Mediapipe-ready update scheduled in the same batch as the deadline tick
+  // will already be visible — closing the race where `setLoadDeadlineExceeded`
+  // and `setMediapipeReady` fire in adjacent microtasks.
+  useEffect(() => {
+    if (hidden || usingSelfieCapture || mediapipeReady) return;
+    if (!loadDeadlineExceeded) return;
+    const legacyFallbackAllowed =
+      allowLegacySelfieFallback || skipMediapipeForTests;
+    if (!legacyFallbackAllowed) return;
+    setUsingSelfieCapture(true);
+  }, [
+    hidden,
+    usingSelfieCapture,
+    mediapipeReady,
+    loadDeadlineExceeded,
+    allowLegacySelfieFallback,
+    skipMediapipeForTests,
+  ]);
 
   useEffect(() => {
-    if (hidden || mediapipeReady || loadingProgress < 100) return undefined;
+    if (hidden || mediapipeReady || !loadDeadlineExceeded) return undefined;
 
     const setupEventForwarding = () => {
       const selfieCapture = document.querySelector('selfie-capture');
@@ -267,7 +406,7 @@ const SelfieCaptureWrapper: FunctionComponent<Props> = ({
     return () => {
       clearTimeout(timeoutId);
     };
-  }, [hidden, mediapipeReady, loadingProgress]);
+  }, [hidden, mediapipeReady, loadDeadlineExceeded]);
 
   // Dispatch allow_legacy_selfie_fallback config for observability
   useEffect(() => {
@@ -298,6 +437,28 @@ 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;
   }
@@ -312,65 +473,91 @@ const SelfieCaptureWrapper: FunctionComponent<Props> = ({
     return <SmartSelfieCapture {...props} />;
   }
 
-  if (loadingProgress >= 100) {
-    // When loading completes without Mediapipe becoming ready, check if legacy
-    // fallback is allowed. Legacy is allowed if:
-    // 1. allow-legacy-selfie-fallback attribute is set to true, OR
-    // 2. Running under Cypress (to keep existing test behavior)
-    const legacyFallbackAllowed = allowLegacySelfieFallback || isCypress;
-
-    if (legacyFallbackAllowed) {
-      // Mount the legacy `selfie-capture` web component. We also set
-      // `usingSelfieCapture` so other effects can react (e.g. metadata dispatch).
-      if (!usingSelfieCapture) {
-        setUsingSelfieCapture(true);
-      }
+  // Legacy capture is mounted only once the latch effect has set
+  // `usingSelfieCapture`. The effect re-checks `mediapipeReady` after commit,
+  // so if Mediapipe became ready in the same batch as the deadline tick, the
+  // latch is skipped and the SmartSelfie branch above wins. While we're
+  // waiting for the effect to fire (a single microtask), keep showing the
+  // spinner instead of flashing legacy.
+  if (usingSelfieCapture) {
+    const propsWithoutHidden = { ...props };
+    delete (propsWithoutHidden as any).hidden;
 
-      const propsWithoutHidden = { ...props };
-      delete (propsWithoutHidden as any).hidden;
+    return (
+      // @ts-expect-error --- preact-custom-element doesn't have proper types for refs
+      <selfie-capture
+        {...propsWithoutHidden}
+        ref={(el: HTMLElement) => {
+          if (el && !el.hasAttribute('data-events-setup')) {
+            el.setAttribute('data-events-setup', 'true');
+
+            const forwardEvent = (event: Event) => {
+              const customEvent = event as CustomEvent;
+
+              if (
+                customEvent.type === 'selfie-capture.publish' ||
+                customEvent.type === 'selfie-capture.cancelled' ||
+                customEvent.type === 'selfie-capture.close'
+              ) {
+                setInitialSessionCompleted(true);
+              }
+
+              window.dispatchEvent(
+                new CustomEvent(customEvent.type, {
+                  detail: customEvent.detail,
+                  bubbles: true,
+                }),
+              );
+            };
+
+            el.addEventListener('selfie-capture.publish', forwardEvent);
+            el.addEventListener('selfie-capture.cancelled', forwardEvent);
+            el.addEventListener('selfie-capture.close', forwardEvent);
+          }
+        }}
+      />
+    );
+  }
 
-      return (
-        // @ts-expect-error --- preact-custom-element doesn't have proper types for refs
-        <selfie-capture
-          {...propsWithoutHidden}
-          ref={(el: HTMLElement) => {
-            if (el && !el.hasAttribute('data-events-setup')) {
-              el.setAttribute('data-events-setup', 'true');
-
-              const forwardEvent = (event: Event) => {
-                const customEvent = event as CustomEvent;
-
-                if (
-                  customEvent.type === 'selfie-capture.publish' ||
-                  customEvent.type === 'selfie-capture.cancelled' ||
-                  customEvent.type === 'selfie-capture.close'
-                ) {
-                  setInitialSessionCompleted(true);
-                }
-
-                window.dispatchEvent(
-                  new CustomEvent(customEvent.type, {
-                    detail: customEvent.detail,
-                    bubbles: true,
-                  }),
-                );
-              };
-
-              el.addEventListener('selfie-capture.publish', forwardEvent);
-              el.addEventListener('selfie-capture.cancelled', forwardEvent);
-              el.addEventListener('selfie-capture.close', forwardEvent);
-            }
-          }}
-        />
-      );
-    }
+  // 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'];
 
-    // Legacy fallback is NOT allowed: show error message
     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>
     );
   }