@smileid/usesmileid 12.0.0-beta01

package/src/presentation/components/use_smile_id_document_frame_glyph.tsx

@@ -0,0 +1,162 @@
+import { memo } from "react";
+import Svg, { Rect } from "react-native-svg";
+
+/**
+ * Translucent in-frame document glyph — the "what to align here" hint shown
+ * while idle/positioning, hidden once capture begins.
+ *
+ * PLACEHOLDER: static card illustration standing in for the per-document-type
+ * capture Lottie (not finalised). Swap point: replace the body with the resolved
+ * Lottie for `documentType` + `isLandscape`; the call site and props stay the same.
+ */
+export type UseSmileIDDocumentFrameGlyphProps = {
+  readonly width: number;
+  readonly height: number;
+  /** Landscape (ID card): photo left + lines right. Portrait: header + lines, photo bottom-left. */
+  readonly isLandscape: boolean;
+  readonly testID?: string;
+};
+
+/** Translucent white — readable over the dimmed feed without hiding it. */
+const GLYPH_COLOR = "#FFFFFF8C"; // white @ ~55%
+/** Faint card fill so the skeleton reads as one document card, not loose bars. */
+const CARD_FILL = "#FFFFFF26"; // white @ ~15%
+const CORNER = 6;
+/** Card-fill corner radius — matches the overlay frame's 8px radius. */
+const FRAME_FILL_CORNER = 8;
+
+export const UseSmileIDDocumentFrameGlyph = memo(
+  function UseSmileIDDocumentFrameGlyph(
+    props: UseSmileIDDocumentFrameGlyphProps,
+  ) {
+    const { width: w, height: h, isLandscape } = props;
+    if (w <= 0 || h <= 0) return null;
+
+    return (
+      <Svg
+        width={w}
+        height={h}
+        viewBox={`0 0 ${w} ${h}`}
+        preserveAspectRatio="none"
+        {...(props.testID !== undefined ? { testID: props.testID } : {})}
+      >
+        {/* Card fill — binds the photo + line skeleton into one document card. */}
+        <Rect
+          x={0}
+          y={0}
+          width={w}
+          height={h}
+          rx={FRAME_FILL_CORNER}
+          fill={CARD_FILL}
+        />
+        {isLandscape ? (
+          <>
+            {/* Portrait photo block (left) */}
+            <Rect
+              x={w * 0.08}
+              y={h * 0.2}
+              width={w * 0.3}
+              height={h * 0.6}
+              rx={CORNER}
+              fill={GLYPH_COLOR}
+            />
+            {/* Text lines (right) */}
+            <Rect
+              x={w * 0.46}
+              y={h * 0.26}
+              width={w * 0.4}
+              height={h * 0.07}
+              rx={CORNER}
+              fill={GLYPH_COLOR}
+            />
+            <Rect
+              x={w * 0.46}
+              y={h * 0.4}
+              width={w * 0.44}
+              height={h * 0.07}
+              rx={CORNER}
+              fill={GLYPH_COLOR}
+            />
+            <Rect
+              x={w * 0.46}
+              y={h * 0.54}
+              width={w * 0.36}
+              height={h * 0.07}
+              rx={CORNER}
+              fill={GLYPH_COLOR}
+            />
+            <Rect
+              x={w * 0.46}
+              y={h * 0.68}
+              width={w * 0.28}
+              height={h * 0.07}
+              rx={CORNER}
+              fill={GLYPH_COLOR}
+            />
+          </>
+        ) : (
+          <>
+            {/* Header band (top) */}
+            <Rect
+              x={w * 0.1}
+              y={h * 0.12}
+              width={w * 0.8}
+              height={h * 0.08}
+              rx={CORNER}
+              fill={GLYPH_COLOR}
+            />
+            <Rect
+              x={w * 0.1}
+              y={h * 0.26}
+              width={w * 0.6}
+              height={h * 0.05}
+              rx={CORNER}
+              fill={GLYPH_COLOR}
+            />
+            <Rect
+              x={w * 0.1}
+              y={h * 0.36}
+              width={w * 0.65}
+              height={h * 0.05}
+              rx={CORNER}
+              fill={GLYPH_COLOR}
+            />
+            {/* Photo block (bottom-left) + lines beside it */}
+            <Rect
+              x={w * 0.1}
+              y={h * 0.56}
+              width={w * 0.3}
+              height={h * 0.28}
+              rx={CORNER}
+              fill={GLYPH_COLOR}
+            />
+            <Rect
+              x={w * 0.46}
+              y={h * 0.6}
+              width={w * 0.44}
+              height={h * 0.05}
+              rx={CORNER}
+              fill={GLYPH_COLOR}
+            />
+            <Rect
+              x={w * 0.46}
+              y={h * 0.7}
+              width={w * 0.4}
+              height={h * 0.05}
+              rx={CORNER}
+              fill={GLYPH_COLOR}
+            />
+            <Rect
+              x={w * 0.46}
+              y={h * 0.8}
+              width={w * 0.3}
+              height={h * 0.05}
+              rx={CORNER}
+              fill={GLYPH_COLOR}
+            />
+          </>
+        )}
+      </Svg>
+    );
+  },
+);

package/src/presentation/components/use_smile_id_document_overlay.tsx

@@ -0,0 +1,245 @@
+import { memo } from "react";
+import { StyleSheet, Text, View } from "react-native";
+import Svg, { Path } from "react-native-svg";
+import type { UseSmileIDTheme } from "../theme/theme";
+import { useUseSmileIDTheme } from "../theme/theme_context";
+import {
+  isDocumentCaptureActive,
+  type UseSmileIDOverlayState as OverlayState,
+} from "../state/use_smile_id_overlay_state";
+import { UseSmileIDDocumentFrameGlyph } from "./use_smile_id_document_frame_glyph";
+
+export type UseSmileIDDocumentOverlayProps = {
+  readonly state: OverlayState;
+  readonly containerWidth: number;
+  readonly containerHeight: number;
+  /** Optional aspect ratio hint — e.g. CR-80 ID card = 1.586. */
+  readonly knownIdAspectRatio?: number;
+  /**
+   * Coaching copy shown in the dark pill below the frame. Rendered here so it
+   * tracks the frame geometry instead of a fixed screen offset.
+   */
+  readonly feedbackText?: string;
+  readonly testID?: string;
+  readonly theme?: UseSmileIDTheme;
+};
+
+/** Gap between the frame's bottom edge and the coaching pill (Figma: 16dp). */
+const CHIP_TOP_GAP = 16;
+
+/**
+ * Fraction of the container width the document frame spans, per orientation.
+ * Matches the Figma capture frames: landscape ID-1 card ≈ 0.53 of the (wide)
+ * screen; portrait booklet / passport ≈ 0.68 of the (narrow) screen.
+ */
+const FRAME_WIDTH_FRACTION_LANDSCAPE = 0.53;
+const FRAME_WIDTH_FRACTION_PORTRAIT = 0.68;
+/** Frame corner radius (matches the bordered frame's `borderRadius`). */
+const FRAME_CORNER_RADIUS = 8;
+/**
+ * Faint black tint over the WHOLE live feed (net ~0.15 inside the frame). A
+ * component constant, not a theme colour — the surround dim (`documentOverlayScrim`)
+ * is the partner-overridable layer.
+ */
+const DOCUMENT_CAMERA_TINT = "#00000026"; // black @15%
+/** Fallback surround dim when the theme omits `documentOverlayScrim`. */
+const DEFAULT_DOCUMENT_OVERLAY_SCRIM = "#00000066"; // black @40%
+
+/**
+ * Document capture frame — two-layer dim (faint full-feed tint + darker surround
+ * outside the cutout, ~0.15 inside / ~0.49 outside) plus a border that flips to
+ * `ovalActive` on `DOCUMENT_READY`. The cutout is one even-odd path, NOT a `<Mask>`:
+ * masks rasterize the full-screen layer to a bitmap on the UI thread per invalidation,
+ * freezing the camera preview. Respects `knownIdAspectRatio`; the frame stays centred.
+ */
+export function UseSmileIDDocumentOverlay(
+  props: UseSmileIDDocumentOverlayProps,
+) {
+  const themeFromContext = useUseSmileIDTheme();
+  const theme = props.theme ?? themeFromContext;
+  const aspect = props.knownIdAspectRatio ?? 1.586;
+  const isLandscapeFrame = aspect >= 1;
+  const frameWidth =
+    props.containerWidth *
+    (isLandscapeFrame
+      ? FRAME_WIDTH_FRACTION_LANDSCAPE
+      : FRAME_WIDTH_FRACTION_PORTRAIT);
+  const frameHeight = frameWidth / aspect;
+  const left = (props.containerWidth - frameWidth) / 2;
+  const top = (props.containerHeight - frameHeight) / 2;
+  // Two-state border: neutral light while idle/positioning, green once committing.
+  const captureActive = isDocumentCaptureActive(props.state);
+  const borderColor = captureActive
+    ? theme.colors.ovalActive
+    : theme.colors.stroke;
+  const surroundColor =
+    theme.colors.documentOverlayScrim ?? DEFAULT_DOCUMENT_OVERLAY_SCRIM;
+
+  if (props.containerWidth <= 0 || props.containerHeight <= 0) {
+    return null;
+  }
+
+  return (
+    <View
+      testID={props.testID}
+      style={StyleSheet.absoluteFill}
+      pointerEvents="none"
+    >
+      {/* Layer 1: faint tint over the whole feed (~0.15 inside-frame dim). */}
+      <View
+        style={[
+          StyleSheet.absoluteFill,
+          { backgroundColor: DOCUMENT_CAMERA_TINT },
+        ]}
+      />
+      {/* Layer 2: darker surround outside the cutout. Memoised so the per-state
+          border flip below never re-rasterizes the scrim. */}
+      <DocumentScrimSurround
+        containerWidth={props.containerWidth}
+        containerHeight={props.containerHeight}
+        frameLeft={left}
+        frameTop={top}
+        frameWidth={frameWidth}
+        frameHeight={frameHeight}
+        cornerRadius={FRAME_CORNER_RADIUS}
+        color={surroundColor}
+      />
+      {/* In-frame document glyph (placeholder for the per-type capture Lottie). */}
+      {!captureActive ? (
+        <View
+          style={{
+            position: "absolute",
+            left,
+            top,
+            width: frameWidth,
+            height: frameHeight,
+          }}
+          pointerEvents="none"
+        >
+          <UseSmileIDDocumentFrameGlyph
+            width={frameWidth}
+            height={frameHeight}
+            isLandscape={isLandscapeFrame}
+          />
+        </View>
+      ) : null}
+      <View
+        style={{
+          position: "absolute",
+          left,
+          top,
+          width: frameWidth,
+          height: frameHeight,
+          borderWidth: 1.5,
+          borderRadius: FRAME_CORNER_RADIUS,
+          borderColor,
+        }}
+      />
+      {/* Coaching pill, anchored just below the frame (Figma off-black pill). */}
+      {props.feedbackText ? (
+        <View
+          style={{
+            position: "absolute",
+            top: top + frameHeight + CHIP_TOP_GAP,
+            start: 0,
+            end: 0,
+            alignItems: "center",
+          }}
+          pointerEvents="none"
+        >
+          <View
+            style={{
+              maxWidth: "85%",
+              borderRadius: 8,
+              backgroundColor: theme.colors.offBlack,
+              paddingHorizontal: theme.spacing.medium,
+              paddingVertical: theme.spacing.small,
+            }}
+          >
+            <Text
+              style={{
+                ...theme.typography.cardTitle,
+                color: "#FFFFFF",
+                textAlign: "center",
+              }}
+              testID="si_document_feedback_text"
+            >
+              {props.feedbackText}
+            </Text>
+          </View>
+        </View>
+      ) : null}
+    </View>
+  );
+}
+
+/**
+ * Darker dim outside the rounded-rect cutout, as one even-odd path (outer rect +
+ * inner rounded-rect windings). Memoised so parent per-frame state never touches it.
+ */
+const DocumentScrimSurround = memo(function DocumentScrimSurround(props: {
+  readonly containerWidth: number;
+  readonly containerHeight: number;
+  readonly frameLeft: number;
+  readonly frameTop: number;
+  readonly frameWidth: number;
+  readonly frameHeight: number;
+  readonly cornerRadius: number;
+  readonly color: string;
+}) {
+  const {
+    containerWidth,
+    containerHeight,
+    frameLeft,
+    frameTop,
+    frameWidth,
+    frameHeight,
+    cornerRadius,
+    color,
+  } = props;
+  // Clamp the radius so a small frame can't produce a self-overlapping path.
+  const radius = Math.min(cornerRadius, frameWidth / 2, frameHeight / 2);
+  const outerPath = `M0 0H${containerWidth}V${containerHeight}H0Z`;
+  const cutoutPath = roundedRectPath(
+    frameLeft,
+    frameTop,
+    frameWidth,
+    frameHeight,
+    radius,
+  );
+  return (
+    <Svg
+      width="100%"
+      height="100%"
+      viewBox={`0 0 ${containerWidth} ${containerHeight}`}
+      preserveAspectRatio="none"
+      style={StyleSheet.absoluteFill}
+    >
+      <Path d={`${outerPath} ${cutoutPath}`} fill={color} fillRule="evenodd" />
+    </Svg>
+  );
+});
+
+/** Closed rounded-rectangle subpath (clockwise) for the frame cutout. */
+function roundedRectPath(
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  r: number,
+): string {
+  const right = x + width;
+  const bottom = y + height;
+  return (
+    `M${x + r} ${y}` +
+    `H${right - r}` +
+    `A${r} ${r} 0 0 1 ${right} ${y + r}` +
+    `V${bottom - r}` +
+    `A${r} ${r} 0 0 1 ${right - r} ${bottom}` +
+    `H${x + r}` +
+    `A${r} ${r} 0 0 1 ${x} ${bottom - r}` +
+    `V${y + r}` +
+    `A${r} ${r} 0 0 1 ${x + r} ${y}` +
+    `Z`
+  );
+}

package/src/presentation/components/use_smile_id_enhanced_smart_selfie_clip.tsx

@@ -0,0 +1,152 @@
+import { useEffect, useRef } from "react";
+import { View, type StyleProp, type ViewStyle } from "react-native";
+import LottieView from "lottie-react-native";
+import type { AnimationObject } from "lottie-react-native";
+import { useReducedMotion } from "../utils/use_reduced_motion";
+import { FaceOvalDefaults } from "./face_oval_defaults";
+import {
+  ENHANCED_SMART_SELFIE_ANIMATION_OPACITY,
+  ENHANCED_SMART_SELFIE_ANIMATION_SPEED,
+  ENHANCED_SMART_SELFIE_TOTAL_FRAMES,
+} from "./helpers/enhanced_smart_selfie_animation_frames";
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+export const ESS_ALL_DIRECTIONS_ANIMATION =
+  require("../assets/si_ess_animation_all_directions.json") as AnimationObject;
+
+/** Square box the Enhanced Smart Selfie cues render in, centred on the oval. */
+export const ENHANCED_SMART_SELFIE_ANIMATION_SIZE = 383;
+/** Nudge so the composition's face lands on the oval centre. */
+export const VERTICAL_ALIGNMENT_OFFSET = -15;
+
+export type UseSmileIDEnhancedSmartSelfieClipProps = {
+  readonly startFrame: number;
+  readonly endFrame: number;
+  /** Play forward-then-back instead of restarting from the first frame. */
+  readonly pingPong: boolean;
+  readonly containerWidth: number;
+  readonly containerHeight: number;
+  readonly testID: string;
+};
+
+/**
+ * Shared renderer for the Enhanced Smart Selfie cues — plays a frame
+ * sub-range of the all-directions composition in a loop, centred on
+ * the face oval. Reduced motion holds the clip's final frame.
+ *
+ * @internal Used by the full / direction ESS animation components.
+ */
+export function UseSmileIDEnhancedSmartSelfieClip(
+  props: UseSmileIDEnhancedSmartSelfieClipProps,
+) {
+  const reducedMotion = useReducedMotion();
+  const { startFrame, endFrame, pingPong, containerWidth, containerHeight } =
+    props;
+
+  if (containerWidth <= 0 || containerHeight <= 0) {
+    return null;
+  }
+
+  const size = ENHANCED_SMART_SELFIE_ANIMATION_SIZE;
+  const ovalCenterY = containerHeight * FaceOvalDefaults.ovalCenterYRatio;
+
+  const containerStyle = {
+    position: "absolute" as const,
+    left: (containerWidth - size) / 2,
+    top: ovalCenterY - size / 2 + VERTICAL_ALIGNMENT_OFFSET,
+    width: size,
+    height: size,
+    // Translucent so the face stays the focal point behind the arrow cue.
+    opacity: ENHANCED_SMART_SELFIE_ANIMATION_OPACITY,
+  };
+
+  if (reducedMotion) {
+    return (
+      <View pointerEvents="none" style={containerStyle} testID={props.testID}>
+        <LottieView
+          source={ESS_ALL_DIRECTIONS_ANIMATION}
+          progress={endFrame / ENHANCED_SMART_SELFIE_TOTAL_FRAMES}
+          autoPlay={false}
+          loop={false}
+          style={{ width: "100%", height: "100%" }}
+        />
+      </View>
+    );
+  }
+
+  if (!pingPong) {
+    // Only the full primer passes pingPong={false}, always with the full range.
+    return (
+      <View pointerEvents="none" style={containerStyle} testID={props.testID}>
+        <LottieView
+          source={ESS_ALL_DIRECTIONS_ANIMATION}
+          autoPlay
+          loop
+          speed={ENHANCED_SMART_SELFIE_ANIMATION_SPEED}
+          style={{ width: "100%", height: "100%" }}
+        />
+      </View>
+    );
+  }
+
+  return (
+    <PingPongClip
+      startFrame={startFrame}
+      endFrame={endFrame}
+      containerStyle={containerStyle}
+      testID={props.testID}
+    />
+  );
+}
+
+type PingPongClipProps = {
+  readonly startFrame: number;
+  readonly endFrame: number;
+  readonly containerStyle: StyleProp<ViewStyle>;
+  readonly testID: string;
+};
+
+/**
+ * Ping-pongs a Lottie sub-range via the imperative play() API —
+ * onAnimationFinish only fires with loop={false}, so each completion
+ * replays with the range reversed.
+ */
+function PingPongClip(props: PingPongClipProps) {
+  const { startFrame, endFrame } = props;
+  const lottieRef = useRef<LottieView>(null);
+  // true = next play is forward (start→end).
+  const forwardRef = useRef(true);
+
+  useEffect(() => {
+    forwardRef.current = true;
+    lottieRef.current?.play(startFrame, endFrame);
+  }, [startFrame, endFrame]);
+
+  const handleAnimationFinish = (isCancelled: boolean) => {
+    if (isCancelled) return;
+    forwardRef.current = !forwardRef.current;
+    if (forwardRef.current) {
+      lottieRef.current?.play(startFrame, endFrame);
+    } else {
+      lottieRef.current?.play(endFrame, startFrame);
+    }
+  };
+
+  return (
+    <View
+      pointerEvents="none"
+      style={props.containerStyle}
+      testID={props.testID}
+    >
+      <LottieView
+        ref={lottieRef}
+        source={ESS_ALL_DIRECTIONS_ANIMATION}
+        loop={false}
+        autoPlay={false}
+        speed={ENHANCED_SMART_SELFIE_ANIMATION_SPEED}
+        onAnimationFinish={handleAnimationFinish}
+        style={{ width: "100%", height: "100%" }}
+      />
+    </View>
+  );
+}

package/src/presentation/components/use_smile_id_enhanced_smart_selfie_direction_animation.tsx

@@ -0,0 +1,46 @@
+import type { ScanHeadTurnDirection } from "@smileid/usesmileid_bridge";
+import { enhancedSmartSelfieFrameRange } from "./helpers/enhanced_smart_selfie_animation_frames";
+import { UseSmileIDEnhancedSmartSelfieClip } from "./use_smile_id_enhanced_smart_selfie_clip";
+
+export type UseSmileIDEnhancedSmartSelfieDirectionAnimationProps = {
+  /** Active head-turn direction from the scan state; null renders nothing. */
+  readonly direction: ScanHeadTurnDirection | null;
+  /**
+   * `true` while the head pose holds {@link direction}. Switches the cue
+   * from the grey "pending" keyframe span to the green "matched" span.
+   */
+  readonly poseMatched: boolean;
+  readonly containerWidth: number;
+  readonly containerHeight: number;
+};
+
+/**
+ * Enhanced Smart Selfie head-turn cue — plays the active direction's
+ * frame sub-range of the all-directions composition, ping-ponging until
+ * the turn completes. Grey while prompting; the range flips to the green
+ * "matched" span once {@link poseMatched} holds. Both the direction and
+ * the pose-match flip switch the frame range IN PLACE on the same Lottie
+ * view (no unmount/remount), so the cue never reinitialises mid-turn.
+ * Reduced motion holds the clip's final (turned-head) frame. Never
+ * mirrored in RTL so the analyzer sees identical expected head-turn
+ * directions in every locale.
+ */
+export function UseSmileIDEnhancedSmartSelfieDirectionAnimation(
+  props: UseSmileIDEnhancedSmartSelfieDirectionAnimationProps,
+) {
+  if (props.direction === null) return null;
+  const { startFrame, endFrame } = enhancedSmartSelfieFrameRange(
+    props.direction,
+    props.poseMatched,
+  );
+  return (
+    <UseSmileIDEnhancedSmartSelfieClip
+      startFrame={startFrame}
+      endFrame={endFrame}
+      pingPong
+      containerWidth={props.containerWidth}
+      containerHeight={props.containerHeight}
+      testID="si_ess_direction_animation"
+    />
+  );
+}

package/src/presentation/components/use_smile_id_enhanced_smart_selfie_full_animation.tsx

@@ -0,0 +1,29 @@
+import { ENHANCED_SMART_SELFIE_TOTAL_FRAMES } from "./helpers/enhanced_smart_selfie_animation_frames";
+import { UseSmileIDEnhancedSmartSelfieClip } from "./use_smile_id_enhanced_smart_selfie_clip";
+
+export type UseSmileIDEnhancedSmartSelfieFullAnimationProps = {
+  readonly containerWidth: number;
+  readonly containerHeight: number;
+};
+
+/**
+ * Enhanced Smart Selfie pre-turn primer — the whole all-directions
+ * composition loops, centred on the face oval. The caller gates
+ * rendering to the idle / instruction states; reduced motion holds the
+ * final frame. Never mirrored in RTL so the analyzer sees identical
+ * expected head-turn directions in every locale.
+ */
+export function UseSmileIDEnhancedSmartSelfieFullAnimation(
+  props: UseSmileIDEnhancedSmartSelfieFullAnimationProps,
+) {
+  return (
+    <UseSmileIDEnhancedSmartSelfieClip
+      startFrame={0}
+      endFrame={ENHANCED_SMART_SELFIE_TOTAL_FRAMES}
+      pingPong={false}
+      containerWidth={props.containerWidth}
+      containerHeight={props.containerHeight}
+      testID="si_ess_full_animation"
+    />
+  );
+}