@velion-la/onboarding-sdk-react-native 1.0.0-beta.2

package/src/camera/LivenessCamera.tsx

@@ -0,0 +1,602 @@
+/**
+ * @fileoverview Liveness camera surface — front-facing vision-camera with an
+ * oval mask, status pill, and capture loop driven by the parent step.
+ *
+ * Capture strategy: vision-camera v4 frame processors run on a worklet thread
+ * and don't expose the JPEG bytes back to JS without a custom native plugin.
+ * We avoid that complication by using `takePhoto({ qualityPrioritization:
+ * 'speed' })` on a JS-level interval (matches the `setInterval` pattern in
+ * `web/LivenessModule.ts`). Real-world FPS lands around 3–8 fps which is
+ * sufficient for Iris's challenge cadence.
+ *
+ * The parent owns the loop and the WebSocket — this component just exposes a
+ * `captureFrame` ref so the step can drive the timing while the camera stays
+ * mounted across challenges.
+ */
+
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from 'react';
+import {
+  ActivityIndicator,
+  Animated,
+  Easing,
+  StyleSheet,
+  Text,
+  useWindowDimensions,
+  View,
+} from 'react-native';
+import Svg, { Defs, Ellipse, Mask, Rect } from 'react-native-svg';
+import {
+  Camera,
+  useCameraDevice,
+  useCameraPermission,
+  type PhotoFile,
+} from 'react-native-vision-camera';
+import { Button } from '../ui/primitives/Button';
+import { useTheme, withAlpha } from '../ui/theme';
+
+export interface LivenessCameraHandle {
+  takeFrame: () => Promise<PhotoFile | null>;
+}
+
+/**
+ * Visual cue applied to the oval guide. The parent maps the current Iris
+ * challenge to one of these so the oval animates in a way that reinforces
+ * the instruction (oval grows for MOVE_CLOSER, shrinks back for MOVE_FARTHER,
+ * stays neutral otherwise).
+ */
+export type LivenessOvalCue = 'NEUTRAL' | 'MOVE_CLOSER' | 'MOVE_FARTHER';
+
+export interface LivenessCameraProps {
+  /** Status text rendered in the centred pill. Pass `null` to hide it. */
+  statusText: string | null;
+  /** Active challenge instruction (rendered above the oval). Optional. */
+  challengeText?: string | null | undefined;
+  /** Visual cue for the oval shape (size animation). Defaults to NEUTRAL. */
+  ovalCue?: LivenessOvalCue | undefined;
+  /** Toast text — passed in as a `{ kind, message }` so the parent owns timing. */
+  toast?: { kind: 'success' | 'warning'; message: string } | null | undefined;
+  /** Linear progress 0–1 shown under the oval (CHALLENGE_PROGRESS). */
+  progress?: number | null | undefined;
+  /** Localized permission denied copy. */
+  permissionDeniedLabel: string;
+  /** Localized retry label for the permission CTA. */
+  retryLabel: string;
+  /** Localized cancel / back label. */
+  cancelLabel: string;
+  onCancel?: (() => void) | undefined;
+}
+
+export const LivenessCamera = forwardRef<LivenessCameraHandle, LivenessCameraProps>(
+  function LivenessCamera(props, ref) {
+    const theme = useTheme();
+    const cameraRef = useRef<Camera>(null);
+    const device = useCameraDevice('front');
+    const { hasPermission, requestPermission } = useCameraPermission();
+    const requestedRef = useRef(false);
+    const inFlightRef = useRef(false);
+    // Same simulator-friendly timeout as DocumentCapture: bail out of the
+    // infinite spinner after 4s without a device.
+    const [deviceTimeout, setDeviceTimeout] = useState(false);
+
+    useEffect(() => {
+      if (!hasPermission && !requestedRef.current) {
+        requestedRef.current = true;
+        void requestPermission();
+      }
+    }, [hasPermission, requestPermission]);
+
+    useEffect(() => {
+      if (device || !hasPermission) {
+        setDeviceTimeout(false);
+        return;
+      }
+      const t = setTimeout(() => setDeviceTimeout(true), 4000);
+      return () => clearTimeout(t);
+    }, [device, hasPermission]);
+
+    const takeFrame = useCallback(async (): Promise<PhotoFile | null> => {
+      if (inFlightRef.current) return null;
+      const camera = cameraRef.current;
+      if (!camera) return null;
+      inFlightRef.current = true;
+      try {
+        return await camera.takePhoto({
+          flash: 'off',
+          enableShutterSound: false,
+        });
+      } catch {
+        // Frame failures are non-fatal — the parent loop just retries on the
+        // next tick. Keep the camera mounted.
+        return null;
+      } finally {
+        inFlightRef.current = false;
+      }
+    }, []);
+
+    useImperativeHandle(ref, () => ({ takeFrame }), [takeFrame]);
+
+    if (!hasPermission) {
+      return (
+        <View style={[styles.permission, { backgroundColor: theme.backgroundColor }]}>
+          <Text style={[styles.permissionText, { color: theme.textColor }]}>
+            {props.permissionDeniedLabel}
+          </Text>
+          <View style={styles.row}>
+            {props.onCancel ? (
+              <Button
+                variant="ghost"
+                label={props.cancelLabel}
+                onPress={props.onCancel}
+                fullWidth={false}
+                style={styles.actionBtn}
+              />
+            ) : null}
+            <Button
+              label={props.retryLabel}
+              onPress={() => {
+                void requestPermission();
+              }}
+              fullWidth={false}
+              style={styles.actionBtn}
+            />
+          </View>
+        </View>
+      );
+    }
+
+    if (!device) {
+      if (deviceTimeout) {
+        return (
+          <View style={[styles.permission, { backgroundColor: theme.backgroundColor }]}>
+            <Text style={[styles.permissionText, { color: theme.textColor }]}>
+              No camera detected. The iOS Simulator does not provide a real
+              camera — please run on a physical device to perform the
+              liveness check.
+            </Text>
+            {props.onCancel ? (
+              <View style={styles.row}>
+                <Button
+                  variant="ghost"
+                  label={props.cancelLabel}
+                  onPress={props.onCancel}
+                  fullWidth={false}
+                  style={styles.actionBtn}
+                />
+              </View>
+            ) : null}
+          </View>
+        );
+      }
+      return (
+        <View style={[styles.permission, { backgroundColor: theme.backgroundColor }]}>
+          <ActivityIndicator color={theme.primaryColor} />
+        </View>
+      );
+    }
+
+    return (
+      <View style={styles.root}>
+        <Camera
+          ref={cameraRef}
+          style={StyleSheet.absoluteFill}
+          device={device}
+          photo
+          photoQualityBalance="speed"
+          // Sin espejo en el output: el preview sigue mirrored, pero el JPEG enviado a Iris mantiene el yaw real (TURN_LEFT/RIGHT).
+          isMirrored={false}
+          isActive
+        />
+        <OvalOverlay
+          primaryColor={theme.primaryColor}
+          cue={props.ovalCue ?? 'NEUTRAL'}
+        />
+        {props.challengeText ? (
+          <ChallengeBanner
+            text={props.challengeText}
+            tint={theme.primaryColor}
+          />
+        ) : null}
+        {props.statusText ? (
+          <View style={styles.statusPill}>
+            <ActivityIndicator color="#FFFFFF" size="small" />
+            <Text style={styles.statusText}>{props.statusText}</Text>
+          </View>
+        ) : null}
+        {props.toast ? (
+          <View
+            style={[
+              styles.toast,
+              {
+                backgroundColor:
+                  props.toast.kind === 'success'
+                    ? withAlpha(theme.successColor, 0.92)
+                    : withAlpha(theme.warningColor, 0.92),
+              },
+            ]}
+          >
+            <Text style={styles.toastText}>{props.toast.message}</Text>
+          </View>
+        ) : null}
+        {props.progress != null ? (
+          <ProgressBar
+            progress={props.progress}
+            color={theme.primaryColor}
+          />
+        ) : null}
+      </View>
+    );
+  },
+);
+
+interface ProgressBarProps {
+  progress: number;
+  color: string;
+}
+
+/**
+ * Challenge progress bar with an indeterminate fallback.
+ *
+ * When the orchestrator hasn't sent any CHALLENGE_PROGRESS yet (still
+ * collecting baseline, user hasn't started moving, etc.) `progress` is 0
+ * and a static empty bar looks broken. We treat the [0, 0.05) range as
+ * "no measurable progress yet" and run a left-to-right shimmer instead,
+ * so the user can tell the system is still listening.
+ */
+function ProgressBar({ progress, color }: ProgressBarProps) {
+  const clamped = Math.max(0, Math.min(1, progress));
+  const isIndeterminate = clamped < 0.05;
+
+  const shimmer = useRef(new Animated.Value(0)).current;
+  useEffect(() => {
+    if (!isIndeterminate) {
+      shimmer.stopAnimation();
+      return;
+    }
+    shimmer.setValue(0);
+    const loop = Animated.loop(
+      Animated.timing(shimmer, {
+        toValue: 1,
+        duration: 1200,
+        easing: Easing.inOut(Easing.ease),
+        useNativeDriver: false,
+      }),
+    );
+    loop.start();
+    return () => loop.stop();
+  }, [isIndeterminate, shimmer]);
+
+  if (isIndeterminate) {
+    // 30 % wide segment sliding from -30 % to +100 % of the track.
+    const left = shimmer.interpolate({
+      inputRange: [0, 1],
+      outputRange: ['-30%', '100%'],
+    });
+    return (
+      <View style={styles.progressTrack}>
+        <Animated.View
+          style={[
+            styles.progressShimmer,
+            { backgroundColor: color, left },
+          ]}
+        />
+      </View>
+    );
+  }
+
+  return (
+    <View style={styles.progressTrack}>
+      <View
+        style={[
+          styles.progressBar,
+          {
+            width: `${clamped * 100}%`,
+            backgroundColor: color,
+          },
+        ]}
+      />
+    </View>
+  );
+}
+
+interface ChallengeBannerProps {
+  text: string;
+  tint: string;
+}
+
+/**
+ * Attention-grabbing challenge instruction.
+ *
+ * The previous small grey pill was easy to miss — users sat confused
+ * while Iris's 800-8000 ms BLINK window closed. This banner is bold,
+ * sits on a dark translucent surface (less visually heavy than a full
+ * primary-tinted fill), and runs a fade-in + scale-up animation every
+ * time the `text` prop changes so the eye snaps to the new instruction.
+ *
+ * The `tint` prop is no longer used for the background (too saturated);
+ * it's kept in the signature for future re-introduction of an accent
+ * line / icon if needed without changing the call site.
+ */
+function ChallengeBanner({ text, tint: _tint }: ChallengeBannerProps) {
+  const opacity = useRef(new Animated.Value(0)).current;
+  const scale = useRef(new Animated.Value(0.85)).current;
+
+  useEffect(() => {
+    // Reset to invisible/shrunk, then animate in. `text` in deps means each
+    // new challenge re-triggers the entrance animation.
+    opacity.setValue(0);
+    scale.setValue(0.85);
+    Animated.parallel([
+      Animated.timing(opacity, {
+        toValue: 1,
+        duration: 240,
+        easing: Easing.out(Easing.cubic),
+        useNativeDriver: true,
+      }),
+      Animated.spring(scale, {
+        toValue: 1,
+        damping: 12,
+        stiffness: 180,
+        mass: 0.7,
+        useNativeDriver: true,
+      }),
+    ]).start();
+  }, [text, opacity, scale]);
+
+  return (
+    <Animated.View
+      pointerEvents="none"
+      style={[
+        styles.challengeBanner,
+        {
+          opacity,
+          transform: [{ scale }],
+        },
+      ]}
+    >
+      <Text style={styles.challengeBannerText} numberOfLines={2}>
+        {text}
+      </Text>
+    </Animated.View>
+  );
+}
+
+interface OvalOverlayProps {
+  primaryColor: string;
+  cue: LivenessOvalCue;
+}
+
+// Face-shaped oval: real human heads have a width-to-height ratio close to
+// ~0.72 (slightly taller than a circle). Sized explicitly from
+// `useWindowDimensions` and rendered as a true ellipse via SVG (NOT a
+// rounded View) so the dim mask can follow the actual curve.
+const OVAL_WIDTH_RATIO = 0.78; // 78 % of screen width
+const OVAL_MAX_HEIGHT_RATIO = 0.62; // never taller than 62 % of screen height
+const OVAL_ASPECT = 0.78; // width / height — face proportion
+// Visual nudge: dim the screen symmetrically around the geometric centre
+// looks slightly low because of the status bar / Dynamic Island at the
+// top. Lift the oval by this many points so the user's natural framing
+// (eyes near the top third of the oval) aligns with the screen's optical
+// centre.
+const OVAL_OPTICAL_OFFSET_UP = 24;
+const OVAL_BORDER_WIDTH = 4;
+// Secondary halo drawn outside the main stroke. Gives the user a clearer
+// "your face should fill this" target without being so heavy that it
+// distracts during the challenges.
+const OVAL_HALO_WIDTH = 2;
+const OVAL_HALO_OFFSET = 6; // px outside the primary stroke
+const DIM_FILL = 'rgba(0, 0, 0, 0.55)';
+// Scale targets per oval cue. The oval visually invites the user to bring
+// their face closer (it grows) on MOVE_CLOSER, and to back away (it shrinks
+// back to neutral size) on MOVE_FARTHER. NEUTRAL is the default oval size.
+const OVAL_SCALE_BY_CUE: Record<LivenessOvalCue, number> = {
+  NEUTRAL: 1.0,
+  MOVE_CLOSER: 1.25,
+  MOVE_FARTHER: 1.0,
+};
+const OVAL_SCALE_ANIM_MS = 600;
+
+function OvalOverlay({ primaryColor, cue }: OvalOverlayProps) {
+  const { width: screenW, height: screenH } = useWindowDimensions();
+
+  // Compute width first, then derive height to keep the face aspect ratio.
+  // If that height would dominate the screen, clip from the height side
+  // instead so the oval stays well within the visible area on tall phones.
+  let ovalW = screenW * OVAL_WIDTH_RATIO;
+  let ovalH = ovalW / OVAL_ASPECT;
+  const maxH = screenH * OVAL_MAX_HEIGHT_RATIO;
+  if (ovalH > maxH) {
+    ovalH = maxH;
+    ovalW = ovalH * OVAL_ASPECT;
+  }
+  const rx = ovalW / 2;
+  const ry = ovalH / 2;
+  const cx = screenW / 2;
+  const cy = Math.max(ry + 20, screenH / 2 - OVAL_OPTICAL_OFFSET_UP);
+
+  // Animate the oval scale on cue changes. We scale the entire Svg via an
+  // Animated.View transform — that keeps the mask + stroke perfectly
+  // aligned (no need to animate every SVG attribute individually). Scaling
+  // the dim rectangle past the screen edge is harmless: the user only sees
+  // the on-screen portion, which is exactly what we want.
+  const ovalScale = useRef(new Animated.Value(OVAL_SCALE_BY_CUE[cue])).current;
+  useEffect(() => {
+    Animated.timing(ovalScale, {
+      toValue: OVAL_SCALE_BY_CUE[cue],
+      duration: OVAL_SCALE_ANIM_MS,
+      easing: Easing.out(Easing.cubic),
+      useNativeDriver: true,
+    }).start();
+  }, [cue, ovalScale]);
+
+  // SVG mask trick:
+  //   - The Mask defines a black/white image where white = "show the masked
+  //     element" and black = "hide it (transparent)".
+  //   - We mask a full-screen dim rectangle so the dim shows EVERYWHERE
+  //     except inside the ellipse (where the mask is black).
+  //   - On top of the dim, we draw the ellipse stroke as the visual
+  //     viewfinder. Stroke is inset half its width so it stays exactly on
+  //     the dim/transparent boundary.
+  return (
+    <Animated.View
+      pointerEvents="none"
+      style={[StyleSheet.absoluteFill, { transform: [{ scale: ovalScale }] }]}
+    >
+      <Svg
+        width={screenW}
+        height={screenH}
+        style={StyleSheet.absoluteFill}
+      >
+        <Defs>
+          <Mask id="ovalCutout">
+            <Rect x={0} y={0} width={screenW} height={screenH} fill="white" />
+            <Ellipse cx={cx} cy={cy} rx={rx} ry={ry} fill="black" />
+          </Mask>
+        </Defs>
+        <Rect
+          x={0}
+          y={0}
+          width={screenW}
+          height={screenH}
+          fill={DIM_FILL}
+          mask="url(#ovalCutout)"
+        />
+        {/* Outer halo: lower-opacity white ring that frames the primary
+            stroke. The pair reads as "here's the target shape" much more
+            clearly than a single 3 px stroke against the live camera feed,
+            especially on Android phones with low-contrast OLED panels. */}
+        <Ellipse
+          cx={cx}
+          cy={cy}
+          rx={rx + OVAL_HALO_OFFSET}
+          ry={ry + OVAL_HALO_OFFSET}
+          stroke="rgba(255, 255, 255, 0.45)"
+          strokeWidth={OVAL_HALO_WIDTH}
+          fill="none"
+        />
+        <Ellipse
+          cx={cx}
+          cy={cy}
+          rx={rx - OVAL_BORDER_WIDTH / 2}
+          ry={ry - OVAL_BORDER_WIDTH / 2}
+          stroke={primaryColor}
+          strokeWidth={OVAL_BORDER_WIDTH}
+          fill="none"
+        />
+      </Svg>
+    </Animated.View>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: {
+    flex: 1,
+    backgroundColor: '#000',
+  },
+  permission: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 32,
+    gap: 16,
+  },
+  permissionText: {
+    textAlign: 'center',
+    fontSize: 15,
+    lineHeight: 22,
+  },
+  row: {
+    flexDirection: 'row',
+    gap: 12,
+    width: '100%',
+    maxWidth: 380,
+  },
+  actionBtn: {
+    flex: 1,
+  },
+  challengeBanner: {
+    position: 'absolute',
+    top: 76,
+    left: 24,
+    right: 24,
+    paddingHorizontal: 16,
+    paddingVertical: 10,
+    borderRadius: 18,
+    alignItems: 'center',
+    justifyContent: 'center',
+    backgroundColor: 'rgba(0, 0, 0, 0.62)',
+  },
+  challengeBannerText: {
+    color: '#FFFFFF',
+    fontSize: 19,
+    fontWeight: '700',
+    textAlign: 'center',
+    letterSpacing: 0.1,
+    lineHeight: 24,
+  },
+  statusPill: {
+    position: 'absolute',
+    top: 130,
+    left: 0,
+    right: 0,
+    alignSelf: 'center',
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: 8,
+    backgroundColor: 'rgba(0,0,0,0.55)',
+    paddingHorizontal: 14,
+    paddingVertical: 8,
+    borderRadius: 16,
+    marginHorizontal: 60,
+    overflow: 'hidden',
+  },
+  statusText: {
+    color: '#FFFFFF',
+    fontSize: 13,
+    fontWeight: '500',
+  },
+  toast: {
+    position: 'absolute',
+    bottom: 100,
+    left: 24,
+    right: 24,
+    paddingVertical: 10,
+    paddingHorizontal: 14,
+    borderRadius: 14,
+    alignItems: 'center',
+  },
+  toastText: {
+    color: '#FFFFFF',
+    fontWeight: '600',
+    fontSize: 14,
+    textAlign: 'center',
+  },
+  progressTrack: {
+    position: 'absolute',
+    bottom: 60,
+    left: 24,
+    right: 24,
+    height: 6,
+    borderRadius: 3,
+    backgroundColor: 'rgba(255,255,255,0.25)',
+    overflow: 'hidden',
+  },
+  progressBar: {
+    height: '100%',
+  },
+  progressShimmer: {
+    position: 'absolute',
+    top: 0,
+    bottom: 0,
+    width: '30%',
+    opacity: 0.85,
+    borderRadius: 3,
+  },
+});