@smileid/usesmileid 12.0.0-beta01

package/src/presentation/components/__tests__/use_smile_id_instructions_hero.test.tsx

@@ -0,0 +1,79 @@
+import { describe, it, expect, vi } from "vitest";
+import * as React from "react";
+import { Animated } from "react-native";
+import { create as createRenderer, act } from "react-test-renderer";
+import {
+  UseSmileIDInstructionsHero,
+  OVAL_PROGRESS_DURATION_MS,
+  loopDurationMs,
+} from "../use_smile_id_instructions_hero";
+import { SELFIE_HERO_ANIMATION } from "../../flow/model/instructions_defaults";
+
+function render(element: React.ReactElement) {
+  let tree!: ReturnType<typeof createRenderer>;
+  act(() => {
+    tree = createRenderer(element);
+  });
+  return tree;
+}
+
+/**
+ * Smoke tests for the hero. The renderer never fires `onLayout`, so the
+ * measured slot stays 0×0 and the SVG/Lottie subtree isn't materialized —
+ * these assert the component mounts and tears down cleanly across the oval
+ * and progress-disabled variants without throwing.
+ */
+describe("UseSmileIDInstructionsHero", () => {
+  it("mounts with a static (no-progress) ring", () => {
+    const { root } = render(
+      <UseSmileIDInstructionsHero
+        source={SELFIE_HERO_ANIMATION}
+        showOval
+        showOvalProgress={false}
+      />,
+    );
+    expect(
+      root.findAllByProps({ testID: "si_instructions_hero" })[0],
+    ).toBeTruthy();
+  });
+
+  it("mounts and unmounts with the progress ring enabled", () => {
+    const tree = render(
+      <UseSmileIDInstructionsHero
+        source={SELFIE_HERO_ANIMATION}
+        showOval
+        showOvalProgress
+      />,
+    );
+    expect(
+      tree.root.findAllByProps({ testID: "si_instructions_hero" })[0],
+    ).toBeTruthy();
+    // Unmount must stop the loop / remove the reduced-motion listener cleanly.
+    act(() => tree.unmount());
+  });
+
+  it("drives the ring fill and the hero on separate, decoupled durations", () => {
+    // Guards the decoupling: the ring fills on the fixed
+    // OVAL_PROGRESS_DURATION_MS loop while the hero plays at its own
+    // composition pace (loopDurationMs(source)). A future refactor that
+    // re-couples the two — or changes the ring duration — fails here.
+    const timingSpy = vi.spyOn(Animated, "timing");
+    try {
+      const tree = render(
+        <UseSmileIDInstructionsHero
+          source={SELFIE_HERO_ANIMATION}
+          showOval
+          showOvalProgress
+        />,
+      );
+      const durations = timingSpy.mock.calls.map(
+        ([, config]) => (config as { duration: number }).duration,
+      );
+      expect(durations).toContain(OVAL_PROGRESS_DURATION_MS);
+      expect(durations).toContain(loopDurationMs(SELFIE_HERO_ANIMATION));
+      act(() => tree.unmount());
+    } finally {
+      timingSpy.mockRestore();
+    }
+  });
+});

package/src/presentation/components/__tests__/use_smile_id_loading_indicator.test.tsx

@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest";
+import * as React from "react";
+import {
+  create as createRenderer,
+  act,
+  type ReactTestInstance,
+} from "react-test-renderer";
+import { UseSmileIDLoadingIndicator } from "../use_smile_id_loading_indicator";
+
+/**
+ * The spinner reads reduced-motion and starts an `Animated.loop` in
+ * effects. These tests assert it mounts without throwing through the
+ * RN mock's `AccessibilityInfo` + `Animated.loop` shims.
+ */
+
+function render(element: React.ReactElement) {
+  let tree!: ReturnType<typeof createRenderer>;
+  act(() => {
+    tree = createRenderer(element);
+  });
+  return tree;
+}
+
+function findByTestID(
+  root: ReactTestInstance,
+  testID: string,
+): ReactTestInstance | null {
+  return root.findAllByProps({ testID })[0] ?? null;
+}
+
+describe("UseSmileIDLoadingIndicator", () => {
+  it("mounts and exposes its testID", () => {
+    const { root } = render(<UseSmileIDLoadingIndicator testID="si_spinner" />);
+    expect(findByTestID(root, "si_spinner")).not.toBeNull();
+  });
+
+  it("unmounts cleanly (stops the loop)", () => {
+    const tree = render(<UseSmileIDLoadingIndicator testID="si_spinner" />);
+    expect(() => {
+      act(() => {
+        tree.unmount();
+      });
+    }).not.toThrow();
+  });
+});

package/src/presentation/components/__tests__/use_smile_id_oval_border_palette.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from "vitest";
+import { UseSmileIDOvalBorderPalette } from "../use_smile_id_oval_border_palette";
+import { UseSmileIDOverlayState } from "../../state/use_smile_id_overlay_state";
+
+/**
+ * Pins the state → color-token table; changes are partner-visible and
+ * must land in lockstep with the sibling SDKs.
+ */
+describe("UseSmileIDOvalBorderPalette", () => {
+  const neutral: UseSmileIDOverlayState[] = [
+    UseSmileIDOverlayState.INSTRUCTION,
+    UseSmileIDOverlayState.IDLE,
+    UseSmileIDOverlayState.FACE_DETECTED,
+    UseSmileIDOverlayState.HEAD_TURN,
+    UseSmileIDOverlayState.MOVE_LEFT,
+    UseSmileIDOverlayState.MOVE_RIGHT,
+    UseSmileIDOverlayState.MOVE_UP,
+    UseSmileIDOverlayState.MOVE_DOWN,
+    UseSmileIDOverlayState.DOCUMENT_NOT_CENTERED,
+    UseSmileIDOverlayState.DOCUMENT_TOO_FAR,
+    UseSmileIDOverlayState.DOCUMENT_TOO_CLOSE,
+    UseSmileIDOverlayState.DOCUMENT_HOLD_STILL,
+    UseSmileIDOverlayState.DOCUMENT_READY,
+  ];
+
+  const active: UseSmileIDOverlayState[] = [
+    UseSmileIDOverlayState.READY,
+    UseSmileIDOverlayState.CAPTURING,
+    UseSmileIDOverlayState.PROCESSING,
+  ];
+
+  const warning: UseSmileIDOverlayState[] = [
+    UseSmileIDOverlayState.TOO_CLOSE,
+    UseSmileIDOverlayState.TOO_FAR,
+    UseSmileIDOverlayState.FACE_NOT_CENTERED,
+    UseSmileIDOverlayState.LOW_LIGHT,
+    UseSmileIDOverlayState.BRIGHT_LIGHT,
+    UseSmileIDOverlayState.WRONG_ORIENTATION,
+    UseSmileIDOverlayState.NOT_SMILING,
+    UseSmileIDOverlayState.MULTIPLE_FACES,
+  ];
+
+  it("covers every overlay state exactly once across the three buckets", () => {
+    const covered = [...neutral, ...active, ...warning];
+    expect(covered.length).toBe(new Set(covered).size);
+    expect(new Set(covered)).toEqual(
+      new Set(Object.values(UseSmileIDOverlayState)),
+    );
+  });
+
+  for (const state of neutral) {
+    it(`maps ${state} to ovalDefault`, () => {
+      expect(UseSmileIDOvalBorderPalette.tokenFor(state, false)).toBe(
+        "ovalDefault",
+      );
+    });
+  }
+
+  for (const state of active) {
+    it(`maps ${state} to ovalActive`, () => {
+      expect(UseSmileIDOvalBorderPalette.tokenFor(state, false)).toBe(
+        "ovalActive",
+      );
+    });
+  }
+
+  for (const state of warning) {
+    it(`maps ${state} to ovalWarning`, () => {
+      expect(UseSmileIDOvalBorderPalette.tokenFor(state, false)).toBe(
+        "ovalWarning",
+      );
+    });
+  }
+
+  it("INSTRUCTION is neutral, not green — the no-green-flash invariant", () => {
+    expect(
+      UseSmileIDOvalBorderPalette.tokenFor(
+        UseSmileIDOverlayState.INSTRUCTION,
+        false,
+      ),
+    ).toBe("ovalDefault");
+  });
+
+  it("Enhanced Smart Selfie keeps CAPTURING / PROCESSING neutral", () => {
+    expect(
+      UseSmileIDOvalBorderPalette.tokenFor(
+        UseSmileIDOverlayState.CAPTURING,
+        true,
+      ),
+    ).toBe("ovalDefault");
+    expect(
+      UseSmileIDOvalBorderPalette.tokenFor(
+        UseSmileIDOverlayState.PROCESSING,
+        true,
+      ),
+    ).toBe("ovalDefault");
+    expect(
+      UseSmileIDOvalBorderPalette.tokenFor(UseSmileIDOverlayState.READY, true),
+    ).toBe("ovalActive");
+  });
+});

package/src/presentation/components/face_oval_defaults.ts

@@ -0,0 +1,51 @@
+/**
+ * Face-oval geometry constants.
+ *
+ * **DO NOT change these without coordinated changes to the
+ * face-detector validators.** Validators tune their
+ * `minFillThreshold` / `maxFillThreshold` against these ratios. Drift
+ * here means head-pose validation misfires on devices that follow
+ * the new ratios while the validator still expects the old ones.
+ *
+ * **No mirroring in RTL.** The oval is centered against
+ * `containerWidth.midX` regardless of locale so the analyzer sees
+ * identical pixel coordinates in `ar`/`he`/`fa`/`ur` as in `en`.
+ */
+export const FaceOvalDefaults = {
+  /** Oval width as a fraction of preview width. */
+  ovalWidthRatio: 0.804,
+  /** Oval height as a fraction of preview height. */
+  ovalHeightRatio: 0.508,
+  /** Oval top edge as a fraction of preview height. */
+  ovalTopRatio: 0.159,
+  /**
+   * Oval vertical centre (`ovalTopRatio + ovalHeightRatio / 2`);
+   * anchors the in-oval coaching and ESS animations.
+   */
+  ovalCenterYRatio: 0.413,
+  /** Top edge of the guidance copy as a fraction of preview height. */
+  feedbackTopRatio: 0.71,
+  /** Stroke width shared by the oval border, track, fill, and directional arc. */
+  strokeWidth: 4,
+  /** Oval-extent fraction the red arc spans from the crowded edge (~90°). */
+  directionalArcEdgeFraction: 0.15,
+} as const;
+
+export type FaceOvalGeometry = {
+  readonly ovalWidth: number;
+  readonly ovalHeight: number;
+  readonly ovalLeft: number;
+  readonly ovalTop: number;
+};
+
+/** Compute the face-oval bounds for a given preview size. */
+export function computeFaceOvalGeometry(
+  containerWidth: number,
+  containerHeight: number,
+): FaceOvalGeometry {
+  const ovalWidth = containerWidth * FaceOvalDefaults.ovalWidthRatio;
+  const ovalHeight = containerHeight * FaceOvalDefaults.ovalHeightRatio;
+  const ovalLeft = (containerWidth - ovalWidth) / 2;
+  const ovalTop = containerHeight * FaceOvalDefaults.ovalTopRatio;
+  return { ovalWidth, ovalHeight, ovalLeft, ovalTop };
+}

package/src/presentation/components/helpers/__tests__/scaled_oval_geometry.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect } from "vitest";
+import { computeScaledOvalGeometry } from "../scaled_oval_geometry";
+import { FaceOvalDefaults } from "../../face_oval_defaults";
+
+describe("computeScaledOvalGeometry", () => {
+  it("renders the oval at full size when the region has ample height", () => {
+    const screenWidth = 400;
+    const screenHeight = 800;
+    // Region tall enough that availableHeight >= full oval height.
+    const regionHeight = 800;
+    const geom = computeScaledOvalGeometry(
+      screenWidth,
+      screenHeight,
+      regionHeight,
+      16,
+    );
+    expect(geom.scale).toBe(1);
+    expect(geom.ovalWidth).toBeCloseTo(
+      screenWidth * FaceOvalDefaults.ovalWidthRatio,
+    );
+    expect(geom.ovalHeight).toBeCloseTo(
+      screenHeight * FaceOvalDefaults.ovalHeightRatio,
+    );
+    expect(geom.ovalTop).toBeCloseTo(
+      screenHeight * FaceOvalDefaults.ovalTopRatio,
+    );
+    // Centered horizontally.
+    expect(geom.ovalLeft).toBeCloseTo((screenWidth - geom.ovalWidth) / 2);
+  });
+
+  it("scales the oval down to fit a short region", () => {
+    const screenWidth = 400;
+    const screenHeight = 800;
+    const regionHeight = 400; // forces a sub-1 scale
+    const geom = computeScaledOvalGeometry(
+      screenWidth,
+      screenHeight,
+      regionHeight,
+      16,
+    );
+    expect(geom.scale).toBeGreaterThan(0);
+    expect(geom.scale).toBeLessThan(1);
+    // The scaled oval + top offset + bottom padding fits within the region.
+    expect(geom.ovalTop + geom.ovalHeight + 16).toBeLessThanOrEqual(
+      regionHeight + 0.001,
+    );
+    // Width and height scale together off the same factor.
+    expect(geom.ovalWidth / geom.ovalHeight).toBeCloseTo(
+      (screenWidth * FaceOvalDefaults.ovalWidthRatio) /
+        (screenHeight * FaceOvalDefaults.ovalHeightRatio),
+    );
+  });
+
+  it("clamps to scale 0 when the region cannot fit any oval (no negative size)", () => {
+    const geom = computeScaledOvalGeometry(400, 800, 100, 16);
+    expect(geom.scale).toBe(0);
+    expect(geom.ovalWidth).toBe(0);
+    expect(geom.ovalHeight).toBe(0);
+  });
+
+  it("guards a zero screen height — returns scale 0, never NaN/Infinity", () => {
+    const geom = computeScaledOvalGeometry(0, 0, 0, 16);
+    expect(geom.scale).toBe(0);
+    expect(Number.isNaN(geom.ovalWidth)).toBe(false);
+    expect(Number.isNaN(geom.ovalHeight)).toBe(false);
+    expect(Number.isFinite(geom.ovalLeft)).toBe(true);
+    expect(Number.isFinite(geom.ovalTop)).toBe(true);
+  });
+});

package/src/presentation/components/helpers/animated_lottie_view.ts

@@ -0,0 +1,9 @@
+import { Animated } from "react-native";
+import LottieView from "lottie-react-native";
+
+/**
+ * Widens `progress` to accept an Animated.Value (lottie-react-native
+ * types it as `number`, but the runtime accepts the value) without an
+ * unsafe cast.
+ */
+export const AnimatedLottieView = Animated.createAnimatedComponent(LottieView);

package/src/presentation/components/helpers/capture_instruction_animation_spec.ts

@@ -0,0 +1,77 @@
+import type { AnimationObject } from "lottie-react-native";
+import type { SiKey } from "../../../l10n/strings_en";
+
+/**
+ * In-oval coaching animation spec, anchored on the face-oval centre.
+ * The box ratios are a cross-platform sizing contract.
+ */
+export type CaptureInstructionAnimationSpec = {
+  /** Stable identity for premounted rendering (React key). */
+  readonly key: string;
+  readonly source: AnimationObject;
+  /** Box width as a fraction of screen width; null → square from heightRatio. */
+  readonly widthRatio: number | null;
+  /** Box height as a fraction of screen height. */
+  readonly heightRatio: number;
+  /** Top edge as a fraction of screen height; null → centre on the face-oval centre. */
+  readonly topOffsetRatio: number | null;
+  readonly resizeMode: "cover" | "contain";
+};
+
+/* eslint-disable @typescript-eslint/no-require-imports */
+const SMILE_TO_CAPTURE_ANIMATION =
+  require("../../assets/si_smile_to_capture_animation.json") as AnimationObject;
+const DARK_LIGHTING_ANIMATION =
+  require("../../assets/si_dark_lighting_animation.json") as AnimationObject;
+const DEVICE_ORIENTATION_ANIMATION =
+  require("../../assets/si_device_orientation_animation.json") as AnimationObject;
+/* eslint-enable @typescript-eslint/no-require-imports */
+
+const SMILE_SPEC: CaptureInstructionAnimationSpec = {
+  key: "smile",
+  source: SMILE_TO_CAPTURE_ANIMATION,
+  widthRatio: null,
+  heightRatio: 0.47,
+  topOffsetRatio: 0.237,
+  resizeMode: "cover",
+};
+
+const LIGHTING_SPEC: CaptureInstructionAnimationSpec = {
+  key: "lighting",
+  source: DARK_LIGHTING_ANIMATION,
+  widthRatio: 1.06,
+  heightRatio: 0.556,
+  topOffsetRatio: null,
+  resizeMode: "cover",
+};
+
+const ROTATE_DEVICE_SPEC: CaptureInstructionAnimationSpec = {
+  key: "rotate-device",
+  source: DEVICE_ORIENTATION_ANIMATION,
+  widthRatio: null,
+  heightRatio: 0.17,
+  topOffsetRatio: null,
+  resizeMode: "contain",
+};
+
+/** Every coaching cue, premounted by the animation component. */
+export const CAPTURE_INSTRUCTION_ANIMATION_SPECS: readonly CaptureInstructionAnimationSpec[] =
+  [SMILE_SPEC, LIGHTING_SPEC, ROTATE_DEVICE_SPEC];
+
+const SPEC_BY_KEY: Partial<Record<SiKey, CaptureInstructionAnimationSpec>> = {
+  si_capture_smile: SMILE_SPEC,
+  si_capture_low_light: LIGHTING_SPEC,
+  si_capture_bright_light: LIGHTING_SPEC,
+  si_capture_rotate_device: ROTATE_DEVICE_SPEC,
+};
+
+/**
+ * Coaching animation for a stable `si_*` feedback key (never the
+ * localised copy), or `null` when the key has no cue.
+ */
+export function captureInstructionAnimationSpec(
+  feedbackKey: SiKey | null,
+): CaptureInstructionAnimationSpec | null {
+  if (feedbackKey === null) return null;
+  return SPEC_BY_KEY[feedbackKey] ?? null;
+}

package/src/presentation/components/helpers/enhanced_smart_selfie_animation_frames.ts

@@ -0,0 +1,70 @@
+import type { ScanHeadTurnDirection } from "@smileid/usesmileid_bridge";
+
+/** A closed `[startFrame, endFrame]` keyframe span within the composition. */
+export type EnhancedSmartSelfieFrameRange = {
+  readonly startFrame: number;
+  readonly endFrame: number;
+};
+
+/**
+ * Per-direction keyframe sub-ranges within the
+ * `si_ess_animation_all_directions` composition (419 frames @ 30 fps).
+ * Each direction splits into a grey `pending` span (the user has not yet
+ * held the requested pose) and a green `matched` span (the pose currently
+ * holds the direction). Pinned against the asset's layer in/out points —
+ * it carries no named markers — so this is a cross-platform contract:
+ * change only in lockstep with the sibling SDKs and re-derive when the
+ * asset changes.
+ */
+export const EnhancedSmartSelfieAnimationFrames = {
+  left: {
+    pending: { startFrame: 1, endFrame: 41 },
+    matched: { startFrame: 42, endFrame: 106 },
+  },
+  right: {
+    pending: { startFrame: 139, endFrame: 179 },
+    matched: { startFrame: 180, endFrame: 241 },
+  },
+  up: {
+    pending: { startFrame: 277, endFrame: 317 },
+    matched: { startFrame: 318, endFrame: 380 },
+  },
+} as const satisfies Record<
+  ScanHeadTurnDirection,
+  {
+    pending: EnhancedSmartSelfieFrameRange;
+    matched: EnhancedSmartSelfieFrameRange;
+  }
+>;
+
+/** Total frame count of the all-directions composition. */
+export const ENHANCED_SMART_SELFIE_TOTAL_FRAMES = 419;
+
+/** Composition frame rate (frames per second). */
+export const ENHANCED_SMART_SELFIE_FRAME_RATE = 30;
+
+/**
+ * Playback rate for the ESS cues. At native speed the arrows read as
+ * hectic while the user mirrors the turn; 0.6× lets the motion be
+ * followed.
+ */
+export const ENHANCED_SMART_SELFIE_ANIMATION_SPEED = 0.6;
+
+/**
+ * Opacity for the ESS cues so the face stays the focal point behind the
+ * translucent arrow overlay.
+ */
+export const ENHANCED_SMART_SELFIE_ANIMATION_OPACITY = 0.75;
+
+/**
+ * Resolve the keyframe span for [direction] — the green `matched` span
+ * while [poseMatched], otherwise the grey `pending` span. Pure, so the
+ * pending↔matched contract is unit-testable without rendering.
+ */
+export function enhancedSmartSelfieFrameRange(
+  direction: ScanHeadTurnDirection,
+  poseMatched: boolean,
+): EnhancedSmartSelfieFrameRange {
+  const ranges = EnhancedSmartSelfieAnimationFrames[direction];
+  return poseMatched ? ranges.matched : ranges.pending;
+}

package/src/presentation/components/helpers/scaled_oval_geometry.ts

@@ -0,0 +1,44 @@
+import { FaceOvalDefaults } from "../face_oval_defaults";
+
+export type ScaledOvalGeometry = {
+  readonly ovalWidth: number;
+  readonly ovalHeight: number;
+  readonly ovalLeft: number;
+  readonly ovalTop: number;
+  /** Applied scale in [0, 1] — 1 means the oval renders at full size. */
+  readonly scale: number;
+};
+
+/**
+ * Scale the canonical face oval down so it fits inside a layout region
+ * of height `regionHeight` without overlapping the card below it.
+ *
+ * The full-size oval is sized against the *screen* (so its proportions
+ * match the live capture screen), then scaled by the ratio of leftover
+ * region height to full oval height, clamped to `[0, 1]`. The oval's top
+ * edge sits at the canonical `ovalTopRatio` of the screen height, and
+ * `bottomPadding` reserves breathing room beneath the oval inside the
+ * region.
+ *
+ * A zero or negative `targetHeight` (degenerate screen size) yields
+ * `scale: 0` rather than `NaN`/`Infinity` from the division.
+ */
+export function computeScaledOvalGeometry(
+  screenWidth: number,
+  screenHeight: number,
+  regionHeight: number,
+  bottomPadding: number,
+): ScaledOvalGeometry {
+  const ovalTop = screenHeight * FaceOvalDefaults.ovalTopRatio;
+  const targetWidth = screenWidth * FaceOvalDefaults.ovalWidthRatio;
+  const targetHeight = screenHeight * FaceOvalDefaults.ovalHeightRatio;
+  const availableHeight = regionHeight - ovalTop - bottomPadding;
+  const scale =
+    targetHeight > 0
+      ? Math.max(0, Math.min(1, availableHeight / targetHeight))
+      : 0;
+  const ovalWidth = targetWidth * scale;
+  const ovalHeight = targetHeight * scale;
+  const ovalLeft = (screenWidth - ovalWidth) / 2;
+  return { ovalWidth, ovalHeight, ovalLeft, ovalTop, scale };
+}