@smileid/usesmileid 12.0.0-beta01

package/src/presentation/screen/helpers/feedback_debouncer.ts

@@ -0,0 +1,89 @@
+/**
+ * Distinct-value trailing debouncer for the capture guidance feed.
+ * The analyzer re-publishes feedback every analyzed frame (~10 Hz),
+ * faster than the window — a naive trailing debounce that reschedules
+ * on every call would never fire. Re-publishing the pending/emitted
+ * value is a no-op (the in-flight window keeps counting); only an
+ * actual change restarts it. `isImmediate` values bypass the window.
+ */
+export class UseSmileIDFeedbackDebouncer<T> {
+  private readonly emit: (value: T) => void;
+  private readonly delayMs: number;
+  private readonly isImmediate: (value: T) => boolean;
+
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private hasEmitted = false;
+  private emittedValue: T | undefined;
+  private pendingValue: T | undefined;
+
+  constructor(options: {
+    readonly emit: (value: T) => void;
+    readonly delayMs: number;
+    readonly isImmediate?: (value: T) => boolean;
+    /** Value the consumer already displays — publishing it again is a no-op. */
+    readonly initialValue?: T;
+  }) {
+    this.emit = options.emit;
+    this.delayMs = options.delayMs;
+    this.isImmediate = options.isImmediate ?? (() => false);
+    if (options.initialValue !== undefined) {
+      this.hasEmitted = true;
+      this.emittedValue = options.initialValue;
+    }
+  }
+
+  publish(value: T): void {
+    if (this.timer !== null) {
+      if (value === this.pendingValue) return;
+    } else if (this.hasEmitted && value === this.emittedValue) {
+      return;
+    }
+
+    this.cancelTimer();
+    if (this.isImmediate(value)) {
+      this.settle(value);
+      return;
+    }
+    this.pendingValue = value;
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      this.settle(value);
+    }, this.delayMs);
+  }
+
+  /**
+   * Forget all state so the next publish goes through even when it
+   * repeats the last emitted value (session reset).
+   */
+  reset(): void {
+    this.cancelTimer();
+    this.hasEmitted = false;
+    this.emittedValue = undefined;
+    this.pendingValue = undefined;
+  }
+
+  /** Emit `value` synchronously and mark it settled (post-reset re-seed). */
+  seed(value: T): void {
+    this.cancelTimer();
+    this.settle(value);
+  }
+
+  /** Cancel any in-flight window without emitting. Call on unmount. */
+  dispose(): void {
+    this.cancelTimer();
+  }
+
+  private settle(value: T): void {
+    this.hasEmitted = true;
+    this.emittedValue = value;
+    this.pendingValue = undefined;
+    this.emit(value);
+  }
+
+  private cancelTimer(): void {
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+}

package/src/presentation/screen/helpers/instructions_screen_helpers.ts

@@ -0,0 +1,108 @@
+import type { UseSmileIDLocalizations } from "../../../l10n/use_smile_id_localizations";
+import type { DocumentType } from "../../../core/models/document_type";
+import type { InstructionGuideline } from "../../flow/model/instruction_guideline";
+import {
+  DOCUMENT_GUIDELINES,
+  documentHeroAnimation,
+  ESS_HERO_ANIMATION,
+  SELFIE_GUIDELINES,
+  SELFIE_HERO_ANIMATION,
+  type HeroAnimationSource,
+} from "../../flow/model/instructions_defaults";
+
+/** Pure resolution helpers, unit-testable without an RN renderer. */
+
+/** The unresolved fields a partner may set on the instructions config. */
+export type InstructionsConfigInput = {
+  readonly titlePrefix?: string;
+  readonly titleEmphasis?: string;
+  readonly heroAnimation?: HeroAnimationSource;
+  readonly guidelinesSectionTitle?: string;
+  readonly guidelines?: readonly InstructionGuideline[];
+  readonly showAttribution?: boolean;
+  readonly showHeroOval?: boolean;
+};
+
+/** Fully-resolved values handed to `UseSmileIDInstructionsScreen`. */
+export type ResolvedInstructions = {
+  readonly titlePrefix: string;
+  readonly titleEmphasis: string;
+  readonly heroSource: HeroAnimationSource;
+  readonly guidelinesSectionTitle: string;
+  readonly guidelines: readonly InstructionGuideline[];
+  readonly showAttribution: boolean;
+  readonly showHeroOval: boolean;
+  readonly showHeroOvalProgress: boolean;
+};
+
+/**
+ * Swaps the default selfie hero for the ESS hero when enhanced liveness is on
+ * and the hero is unset; a partner-supplied hero is always respected.
+ */
+export function resolvedHeroAnimation(
+  heroAnimation: HeroAnimationSource | undefined,
+  enhancedLivenessEnabled: boolean,
+): HeroAnimationSource {
+  if (enhancedLivenessEnabled && heroAnimation === undefined) {
+    return ESS_HERO_ANIMATION;
+  }
+  return heroAnimation ?? SELFIE_HERO_ANIMATION;
+}
+
+/**
+ * Resolve the config into concrete screen props (explicit value > localized /
+ * shared default). When `options.documentType` is set, renders the document
+ * variant: title emphasis ← `displayName`, document hero + guidelines, face
+ * oval forced off. Partner-set title/guidelines/hero still win; the oval does
+ * not (a document has no face).
+ */
+export function resolveInstructionsConfig(
+  config: InstructionsConfigInput,
+  options: {
+    readonly enhancedLivenessEnabled: boolean;
+    readonly documentType?: DocumentType;
+  },
+  localizations: Pick<
+    UseSmileIDLocalizations,
+    | "siInstructionsTitlePrefix"
+    | "siInstructionsEmphasisSelfie"
+    | "siInstructionsCaptureGuidelines"
+  >,
+): ResolvedInstructions {
+  const enhanced = options.enhancedLivenessEnabled;
+  const documentType = options.documentType;
+  const isDocument = documentType !== undefined;
+
+  const defaultGuidelines = isDocument
+    ? DOCUMENT_GUIDELINES
+    : SELFIE_GUIDELINES;
+  const guidelines =
+    config.guidelines && config.guidelines.length > 0
+      ? config.guidelines
+      : defaultGuidelines;
+
+  const titleEmphasis =
+    config.titleEmphasis ??
+    (isDocument
+      ? documentType.displayName
+      : localizations.siInstructionsEmphasisSelfie);
+
+  const heroSource = isDocument
+    ? (config.heroAnimation ?? documentHeroAnimation(documentType))
+    : resolvedHeroAnimation(config.heroAnimation, enhanced);
+
+  return {
+    titlePrefix: config.titlePrefix ?? localizations.siInstructionsTitlePrefix,
+    titleEmphasis,
+    heroSource,
+    guidelinesSectionTitle:
+      config.guidelinesSectionTitle ??
+      localizations.siInstructionsCaptureGuidelines,
+    guidelines,
+    showAttribution: config.showAttribution ?? true,
+    // A document flow never shows the face oval — the override applies to
+    // selfie flows only (a document has no face to frame).
+    showHeroOval: isDocument ? false : (config.showHeroOval ?? true),
+    showHeroOvalProgress: isDocument ? false : !enhanced,
+  };
+}

package/src/presentation/screen/helpers/preview_screen_helpers.ts

@@ -0,0 +1,41 @@
+/**
+ * Pure-logic helpers for `UseSmileIDPreviewScreen`. Extracted so the
+ * accept-button enablement rule and image-presence guard can be
+ * unit-tested without an RN renderer.
+ */
+
+export type PreviewState = {
+  readonly hasImage: boolean;
+  readonly canAccept: boolean;
+  readonly canRetake: boolean;
+};
+
+export type PreviewStateInput = {
+  /** Captured image file path. Empty / null when no capture happened yet. */
+  readonly capturedSelfiePath?: string;
+  /** Partner-controlled retake allowance (defaults to true). */
+  readonly allowRetake?: boolean;
+};
+
+/**
+ * Resolve the screen's button enablement state.
+ *
+ *   - `hasImage`: there's something to preview. Drives the visual
+ *     branch (image card vs. empty fallback).
+ *   - `canAccept`: an image must exist; otherwise the Accept button
+ *     would advance the flow on a non-existent capture.
+ *   - `canRetake`: image must exist AND `allowRetake !== false`. When
+ *     the partner forces `allowRetake: false`, the Reject button
+ *     hides — the user has already committed.
+ */
+export function resolvePreviewState(props: PreviewStateInput): PreviewState {
+  const hasImage =
+    typeof props.capturedSelfiePath === "string" &&
+    props.capturedSelfiePath.length > 0;
+  const allowRetake = props.allowRetake ?? true;
+  return {
+    hasImage,
+    canAccept: hasImage,
+    canRetake: hasImage && allowRetake,
+  };
+}

package/src/presentation/screen/helpers/processing_screen_helpers.ts

@@ -0,0 +1,27 @@
+import { UseSmileIDOverlayState } from "../../state/use_smile_id_overlay_state";
+import type { UseSmileIDOverlayState as OverlayState } from "../../state/use_smile_id_overlay_state";
+
+/**
+ * Pure-logic helpers for `UseSmileIDProcessingScreen`. The visual
+ * branches by `state.kind`; this maps each kind to the matching
+ * overlay-border state so the face oval colour transitions cleanly:
+ *
+ *   loading → CAPTURING (blue)
+ *   success → READY (green)
+ *   failure → IDLE (default)
+ */
+
+export type ProcessingStateKind = "loading" | "success" | "failed";
+
+export function resolveOverlayStateForProcessing(
+  kind: ProcessingStateKind,
+): OverlayState {
+  switch (kind) {
+    case "loading":
+      return UseSmileIDOverlayState.PROCESSING;
+    case "success":
+      return UseSmileIDOverlayState.READY;
+    case "failed":
+      return UseSmileIDOverlayState.IDLE;
+  }
+}

package/src/presentation/screen/helpers/scan_state_to_overlay_state.ts

@@ -0,0 +1,128 @@
+import type { ScanState } from "@smileid/usesmileid_bridge";
+import { ScanStateType } from "@smileid/usesmileid_bridge";
+import { CaptureType } from "../../../core/models/ml_config";
+import { UseSmileIDOverlayState } from "../../state/use_smile_id_overlay_state";
+
+/**
+ * Map an analyzer's `ScanState` into the SDK's visual `OverlayState`.
+ *
+ * The overlay enum drives the face/document oval's border colour, dash
+ * pattern, and fill animation — it's a presentation concept layered on
+ * top of the scan-state machine. The mapping reads `state.feedback`
+ * (when `type === ScanStateType.Found`) and `state.reason` (when
+ * `type === ScanStateType.Unsatisfied`) to pick the fine-grained
+ * overlay state; other scan-state types map coarsely to the matching
+ * lifecycle entry.
+ *
+ * Unrecognised feedback / reason strings fall back to the green-solid
+ * `FACE_DETECTED` / orange-solid `FACE_NOT_CENTERED` defaults rather
+ * than throwing — keeps the overlay alive when a native plugin emits
+ * a new feedback key the JS side hasn't been updated for.
+ */
+export function mapScanStateToOverlayState(
+  scanState: ScanState,
+  captureType: CaptureType,
+): UseSmileIDOverlayState {
+  switch (scanState.type) {
+    case ScanStateType.Initial:
+      return UseSmileIDOverlayState.INSTRUCTION;
+
+    case ScanStateType.Found:
+      // `feedback` is the canonical `si_capture_*` key the native side
+      // emits; partner code never sees raw English copy.
+      return resolveFeedbackOverlay(
+        scanState.feedback,
+        captureType,
+        captureType === CaptureType.selfie
+          ? UseSmileIDOverlayState.FACE_DETECTED
+          : UseSmileIDOverlayState.DOCUMENT_READY,
+      );
+
+    case ScanStateType.Satisfied:
+      return UseSmileIDOverlayState.READY;
+
+    case ScanStateType.Unsatisfied:
+      return resolveFeedbackOverlay(
+        scanState.reason,
+        captureType,
+        captureType === CaptureType.selfie
+          ? UseSmileIDOverlayState.FACE_NOT_CENTERED
+          : UseSmileIDOverlayState.DOCUMENT_NOT_CENTERED,
+      );
+
+    case ScanStateType.Finished:
+      return UseSmileIDOverlayState.CAPTURING;
+
+    case ScanStateType.HeadTurn:
+      return UseSmileIDOverlayState.HEAD_TURN;
+
+    case ScanStateType.Timeout:
+      // Back to the gray pre-capture state while partners re-prompt.
+      return UseSmileIDOverlayState.IDLE;
+  }
+}
+
+/**
+ * Translate a native `si_capture_*` feedback / reason key into the
+ * corresponding overlay state. Unknown keys return the supplied
+ * `fallback` so the overlay keeps animating even when the native
+ * plugin emits a key the JS side hasn't been updated for.
+ */
+function resolveFeedbackOverlay(
+  key: string | undefined,
+  captureType: CaptureType,
+  fallback: UseSmileIDOverlayState,
+): UseSmileIDOverlayState {
+  if (!key) return fallback;
+
+  if (captureType === CaptureType.selfie) {
+    switch (key) {
+      case "si_capture_too_close":
+        return UseSmileIDOverlayState.TOO_CLOSE;
+      case "si_capture_too_far":
+        return UseSmileIDOverlayState.TOO_FAR;
+      case "si_capture_multiple_faces":
+        return UseSmileIDOverlayState.MULTIPLE_FACES;
+      case "si_capture_center_face":
+        return UseSmileIDOverlayState.FACE_NOT_CENTERED;
+      case "si_capture_low_light":
+        return UseSmileIDOverlayState.LOW_LIGHT;
+      case "si_capture_bright_light":
+        return UseSmileIDOverlayState.BRIGHT_LIGHT;
+      case "si_capture_wrong_orientation":
+      case "si_capture_rotate_device":
+        return UseSmileIDOverlayState.WRONG_ORIENTATION;
+      case "si_capture_smile":
+        return UseSmileIDOverlayState.NOT_SMILING;
+      // Directional hints: "higher"/"lower" name the device motion,
+      // mapping to the top/bottom oval edge.
+      case "si_capture_move_left":
+        return UseSmileIDOverlayState.MOVE_LEFT;
+      case "si_capture_move_right":
+        return UseSmileIDOverlayState.MOVE_RIGHT;
+      case "si_capture_move_higher":
+        return UseSmileIDOverlayState.MOVE_UP;
+      case "si_capture_move_lower":
+        return UseSmileIDOverlayState.MOVE_DOWN;
+      default:
+        return fallback;
+    }
+  }
+
+  // captureType === "document"
+  switch (key) {
+    case "si_capture_too_close":
+    case "si_document_too_close":
+      return UseSmileIDOverlayState.DOCUMENT_TOO_CLOSE;
+    case "si_capture_too_far":
+    case "si_document_too_far":
+      return UseSmileIDOverlayState.DOCUMENT_TOO_FAR;
+    case "si_document_center":
+      return UseSmileIDOverlayState.DOCUMENT_NOT_CENTERED;
+    case "si_capture_hold_still":
+    case "si_document_hold_still":
+      return UseSmileIDOverlayState.DOCUMENT_HOLD_STILL;
+    default:
+      return fallback;
+  }
+}

package/src/presentation/screen/helpers/use_capture_orientation_lock.ts

@@ -0,0 +1,46 @@
+import { useEffect } from "react";
+import * as ScreenOrientation from "expo-screen-orientation";
+import { UseSmileIDCrashReporting } from "@smileid/usesmileid_bridge";
+import type { DocumentOrientation } from "../../../core/models/document_type";
+
+/**
+ * Lock device orientation for a capture screen, scoped to its lifetime
+ * (`"Landscape"` → landscape, `"Portrait"` → portrait-up).
+ *
+ * Each screen asserts its OWN orientation on mount, so document → selfie
+ * reverts deterministically rather than depending on the previous
+ * screen's teardown winning a race against the next camera initialising.
+ * Unmount restores portrait-up as a safety net.
+ *
+ * Locks are global: the host app must permit the locked orientations at
+ * the OS level (iOS `UISupportedInterfaceOrientations`, Android activity
+ * `screenOrientation`) for the lock to take effect.
+ */
+export function useCaptureOrientationLock(
+  orientation: DocumentOrientation,
+): void {
+  useEffect(() => {
+    const target =
+      orientation === "Landscape"
+        ? ScreenOrientation.OrientationLock.LANDSCAPE
+        : ScreenOrientation.OrientationLock.PORTRAIT_UP;
+    void lockOrientation(target);
+
+    return () => {
+      void lockOrientation(ScreenOrientation.OrientationLock.PORTRAIT_UP);
+    };
+  }, [orientation]);
+}
+
+/** Lock to `target`, routing a native failure through crash reporting. */
+async function lockOrientation(
+  target: ScreenOrientation.OrientationLock,
+): Promise<void> {
+  try {
+    await ScreenOrientation.lockAsync(target);
+  } catch (error) {
+    UseSmileIDCrashReporting.captureException(
+      error instanceof Error ? error : new Error(String(error)),
+    );
+  }
+}

package/src/presentation/screen/helpers/use_debounced_feedback_key.ts

@@ -0,0 +1,52 @@
+import { useEffect, useRef, useState } from "react";
+import type { SiKey } from "../../../l10n/strings_en";
+import { UseSmileIDMotion } from "../../theme/use_smile_id_motion";
+import { UseSmileIDFeedbackDebouncer } from "./feedback_debouncer";
+
+/** Terminal copy that must appear the instant the scan completes. */
+const IMMEDIATE_FEEDBACK_KEYS: ReadonlySet<SiKey> = new Set<SiKey>([
+  "si_selfie_capture_complete",
+  "si_document_capture_complete",
+]);
+
+/**
+ * Settle the guidance key over `UseSmileIDMotion.feedbackDebounce` so
+ * per-frame churn doesn't flicker the copy or the coaching animation.
+ * The rim, fill, and head-turn direction must NOT go through this hook.
+ * Bump `sessionEpoch` on a session restart to reset and re-seed.
+ */
+export function useDebouncedFeedbackKey(
+  feedbackKey: SiKey,
+  sessionEpoch: number = 0,
+): SiKey {
+  const [settledKey, setSettledKey] = useState<SiKey>(feedbackKey);
+
+  const debouncerRef = useRef<UseSmileIDFeedbackDebouncer<SiKey> | null>(null);
+  if (debouncerRef.current === null) {
+    debouncerRef.current = new UseSmileIDFeedbackDebouncer<SiKey>({
+      emit: setSettledKey,
+      delayMs: UseSmileIDMotion.feedbackDebounce,
+      isImmediate: (value) => IMMEDIATE_FEEDBACK_KEYS.has(value),
+      initialValue: feedbackKey,
+    });
+  }
+
+  const lastEpochRef = useRef(sessionEpoch);
+  useEffect(() => {
+    const debouncer = debouncerRef.current;
+    if (!debouncer) return;
+    if (lastEpochRef.current !== sessionEpoch) {
+      lastEpochRef.current = sessionEpoch;
+      debouncer.reset();
+      debouncer.seed(feedbackKey);
+      return;
+    }
+    debouncer.publish(feedbackKey);
+  }, [feedbackKey, sessionEpoch]);
+
+  // Cancel the in-flight window so the timer never lands a setState
+  // on an unmounted component.
+  useEffect(() => () => debouncerRef.current?.dispose(), []);
+
+  return settledKey;
+}