@smileid/usesmileid 12.0.1 → 12.1.0

package/src/camera/use_smile_id_camera_preview.tsx

@@ -1,256 +0,0 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import type { ReactNode } from "react";
-import {
-  Pressable,
-  StyleSheet,
-  View,
-  type GestureResponderEvent,
-  type LayoutChangeEvent,
-  type StyleProp,
-  type ViewStyle,
-} from "react-native";
-import {
-  Camera,
-  useCameraDevice,
-  useCameraFormat,
-  VisionCameraProxy,
-} from "react-native-vision-camera";
-import { useFrameProcessor } from "react-native-vision-camera";
-import { Worklets } from "react-native-worklets-core";
-import { FrameProcessorPluginNotRegisteredException } from "@smileid/usesmileid_bridge";
-import { CameraDefaults } from "./camera_defaults";
-import { orientationToDegrees } from "./orientation_degrees";
-import type { UseSmileIDCameraSystem } from "./use_smile_id_camera_system";
-import type { CameraSystemState } from "./camera_configuration";
-import type { FocusState } from "./focus_state";
-
-/**
- * Per-frame analysis wiring for the preview. Pixels never cross into
- * JS: the named native frame processor plugin runs the provider's scan
- * session and the worklet forwards only the result map to `onResult`
- * on the JS thread.
- */
-export type UseSmileIDFrameAnalysis = {
-  /** VisionCamera frame-processor plugin name — the analyzer's `frameProcessorPluginName`. */
-  readonly pluginName: string;
-  /**
-   * Receives each frame's raw scan-result map (JS thread); feed it
-   * `useSmileIDFrameStream(...).onFrameResult`. Memoise the
-   * `frameAnalysis` object — a new identity per render rebuilds the
-   * worklet bridge and the camera frame processor.
-   */
-  readonly onResult: (rawResult: unknown) => void;
-  /**
-   * Called once if the named plugin isn't registered natively. Without
-   * a handler the failure is silent — frames never produce results.
-   */
-  readonly onError?: (error: unknown) => void;
-};
-
-export type UseSmileIDCameraPreviewProps = {
-  /** The orchestrator instance — partner creates with `new UseSmileIDCameraSystem()`. */
-  readonly cameraSystem: UseSmileIDCameraSystem;
-  /**
-   * Optional per-frame analysis wiring — the preview initialises the
-   * named plugin and streams each frame's scan-result map to `onResult`.
-   */
-  readonly frameAnalysis?: UseSmileIDFrameAnalysis;
-  /**
-   * Overlay children (face oval, focus reticle, partner branding).
-   * Receives the live `state` and `focusState` via the function-as-
-   * children form so overlays react to focus transitions without
-   * subscribing to the system manually.
-   */
-  readonly children?:
-    | ReactNode
-    | ((args: {
-        readonly state: CameraSystemState;
-        readonly focusState: FocusState;
-      }) => ReactNode);
-  readonly style?: StyleProp<ViewStyle>;
-};
-
-/**
- * Camera preview component.
- *
- * Wraps `react-native-vision-camera`'s `<Camera>`, attaches its ref
- * to the supplied `cameraSystem` so the orchestrator can drive still
- * captures + tap-to-focus, and — when `frameAnalysis` is supplied —
- * wires a frame processor that runs the provider's native plugin per
- * frame and streams its result maps to the JS thread.
- *
- * Lifecycle: ref attaches on mount, detaches on unmount. Partners
- * call `cameraSystem.start()` once they're ready for the camera to
- * begin streaming (typically inside a `useEffect` watching the active
- * `FlowStep`); the preview reads `state.isStreaming` to drive the
- * `<Camera isActive>` prop.
- */
-export function UseSmileIDCameraPreview({
-  cameraSystem,
-  frameAnalysis,
-  children,
-  style,
-}: UseSmileIDCameraPreviewProps) {
-  const cameraRef = useRef<Camera | null>(null);
-  const [state, setState] = useState<CameraSystemState>(() =>
-    cameraSystem.getState(),
-  );
-  const [focusState, setFocusState] = useState<FocusState>(() =>
-    cameraSystem.getFocusState(),
-  );
-  const [viewSize, setViewSize] = useState<{ width: number; height: number }>({
-    width: 0,
-    height: 0,
-  });
-
-  const device = useCameraDevice(state.currentLens);
-  // Pin a 30 fps capture format at ~720p — explicit selection avoids
-  // vision-camera's default "highest supported" heuristic which on
-  // some devices lands on 60 fps with shorter per-frame exposure
-  // (more visible ISO noise) or a much higher resolution than the
-  // analysis pipeline needs.
-  const format = useCameraFormat(device, [
-    // 4:3 first: the scan sessions' geometry checks and smile heuristic
-    // are calibrated on 4:3 frames — 16:9 skews normalized landmark
-    // ratios and silently shifts every threshold.
-    { videoAspectRatio: 4 / 3 },
-    {
-      videoResolution: {
-        width: CameraDefaults.analysisTargetResolution.width,
-        height: CameraDefaults.analysisTargetResolution.height,
-      },
-    },
-    { fps: CameraDefaults.analysisTargetFps },
-  ]);
-  const fps =
-    cameraSystem.getConfiguration().fps ?? CameraDefaults.analysisTargetFps;
-
-  // Subscribe once. cameraSystem reference is stable across renders
-  // when the partner holds it in a `useMemo` — re-running the effect
-  // would leak listeners.
-  useEffect(() => {
-    return cameraSystem.subscribe((nextState, nextFocus) => {
-      setState(nextState);
-      setFocusState(nextFocus);
-    });
-  }, [cameraSystem]);
-
-  // Attach the Camera ref once mounted. Detach on unmount so the
-  // system doesn't try to drive a torn-down view (e.g. `focus()`).
-  useEffect(() => {
-    cameraSystem.attachRef(cameraRef.current);
-    return () => {
-      cameraSystem.attachRef(null);
-    };
-  }, [cameraSystem]);
-
-  // `null` when analysis is off or the plugin isn't registered natively.
-  const pluginName = frameAnalysis?.pluginName ?? null;
-  const plugin = useMemo(() => {
-    if (pluginName === null) return null;
-    return VisionCameraProxy.initFrameProcessorPlugin(pluginName, {}) ?? null;
-  }, [pluginName]);
-
-  // Surface a missing plugin once per name — otherwise the worklet
-  // silently no-ops on every frame. The handler ref keeps an unstable
-  // `onError` identity from re-firing the effect.
-  const onAnalysisErrorRef = useRef(frameAnalysis?.onError);
-  useEffect(() => {
-    onAnalysisErrorRef.current = frameAnalysis?.onError;
-  }, [frameAnalysis?.onError]);
-  useEffect(() => {
-    if (pluginName === null || plugin !== null) return;
-    onAnalysisErrorRef.current?.(
-      new FrameProcessorPluginNotRegisteredException({ pluginName }),
-    );
-  }, [pluginName, plugin]);
-
-  // `Worklets.createRunOnJS` posts results to the JS runtime without
-  // blocking the worklet. Backpressure lives natively: the plugin
-  // blocks the frame-processor thread per scan, so mid-scan frames are
-  // dropped before reaching JS.
-  const onFrameResult = frameAnalysis?.onResult ?? null;
-  const onResultRunOnJS = useMemo(() => {
-    if (!onFrameResult) return null;
-    return Worklets.createRunOnJS((rawResult: unknown) => {
-      onFrameResult(rawResult);
-    });
-  }, [onFrameResult]);
-
-  // Physical device tilt (0 = upright portrait) for the native
-  // session's upright validator and head-pose math; gravity-sourced,
-  // never derived from `frame.orientation` (fixed sensor mounting).
-  const [deviceOrientationDegrees, setDeviceOrientationDegrees] = useState(0);
-
-  const frameProcessor = useFrameProcessor(
-    (frame) => {
-      "worklet";
-      if (!plugin || !onResultRunOnJS) return;
-      const rawResult = plugin.call(frame, {
-        rotation: deviceOrientationDegrees,
-      });
-      onResultRunOnJS(rawResult);
-    },
-    [plugin, onResultRunOnJS, deviceOrientationDegrees],
-  );
-
-  const handleLayout = useCallback((event: LayoutChangeEvent) => {
-    const { width, height } = event.nativeEvent.layout;
-    setViewSize({ width, height });
-  }, []);
-
-  const handleTap = useCallback(
-    (event: GestureResponderEvent) => {
-      if (viewSize.width === 0 || viewSize.height === 0) return;
-      const { locationX, locationY } = event.nativeEvent;
-      void cameraSystem.tapToFocus({
-        x: locationX / viewSize.width,
-        y: locationY / viewSize.height,
-      });
-    },
-    [cameraSystem, viewSize.height, viewSize.width],
-  );
-
-  const overlay =
-    typeof children === "function" ? children({ state, focusState }) : children;
-
-  return (
-    <View style={[styles.container, style]} onLayout={handleLayout}>
-      {device ? (
-        <Camera
-          ref={cameraRef}
-          style={StyleSheet.absoluteFill}
-          device={device}
-          fps={fps}
-          isActive={state.isStreaming}
-          photo={true}
-          // Gravity-based device orientation — keeps reporting tilt even
-          // when the app's UI orientation is locked to portrait.
-          outputOrientation="device"
-          onOutputOrientationChanged={(orientation) => {
-            setDeviceOrientationDegrees(orientationToDegrees(orientation));
-          }}
-          // Conditional spreads instead of `prop={undefined}` —
-          // `exactOptionalPropertyTypes` in tsconfig rejects passing
-          // `undefined` to an optional prop, so we omit the key when
-          // the value is missing.
-          {...(format ? { format } : {})}
-          {...(plugin && onResultRunOnJS ? { frameProcessor } : {})}
-        />
-      ) : null}
-      <Pressable
-        style={StyleSheet.absoluteFill}
-        onPress={handleTap}
-        // Pass-through hit testing for partner overlay UIs that need
-        // to capture taps themselves (buttons, links, etc.).
-        pointerEvents="box-none"
-      >
-        {overlay}
-      </Pressable>
-    </View>
-  );
-}
-
-const styles = StyleSheet.create({
-  container: { flex: 1, backgroundColor: "black", overflow: "hidden" },
-});

package/src/camera/use_smile_id_camera_system.ts

@@ -1,236 +0,0 @@
-import type { Camera } from "react-native-vision-camera";
-import { CameraDefaults } from "./camera_defaults";
-import { CameraLens } from "./camera_lens";
-import type {
-  CameraConfiguration,
-  CameraSystemState,
-} from "./camera_configuration";
-import type { FocusPoint, FocusState } from "./focus_state";
-import { FocusStates } from "./focus_state";
-import {
-  getCameraPermissionStatus,
-  requestCameraPermission,
-} from "./camera_permissions";
-import { UseSmileIDCrashReporting } from "@smileid/usesmileid_bridge";
-
-/**
- * Camera orchestrator.
- *
- * Key responsibilities:
- *   1. Drive permission prompt + state
- *   2. Toggle the camera on/off — frame streaming itself lives in
- *      `<UseSmileIDCameraPreview>`'s `useFrameProcessor` worklet, so
- *      this class doesn't own the frame loop
- *   3. Surface tap-to-focus — drives the visual reticle and calls
- *      `Camera.focus(point)` so the lens actually re-focuses
- *
- * The SDK does not ship a still-capture API. Per-frame analysis via
- * `analyzer.analyze(bytes, metadata, rotation)` + `flush()` is the
- * canonical capture path; the `UseSmileIDCaptureScreen` owns that
- * wiring end-to-end.
- *
- * Lifecycle: `configure(config)` then `start()` to flip the running
- * state on (camera renders in preview), `stop()` to pause without
- * tearing down the React tree, `release()` to detach all refs and
- * mark the system unusable. After `release()`, `start()` throws.
- */
-
-type CameraInstance = Camera;
-type Listener = (state: CameraSystemState, focus: FocusState) => void;
-
-export class UseSmileIDCameraSystem {
-  private _cameraRef: CameraInstance | null = null;
-  private _state: CameraSystemState;
-  private _focusState: FocusState = FocusStates.unspecified();
-  private readonly _listeners = new Set<Listener>();
-  private _config: CameraConfiguration = {};
-  private _released = false;
-  private _focusRunningTimeout: ReturnType<typeof setTimeout> | null = null;
-  private _focusSettledTimeout: ReturnType<typeof setTimeout> | null = null;
-
-  constructor(initialLens: CameraLens = CameraLens.front) {
-    this._state = {
-      isCameraRunning: false,
-      isStreaming: false,
-      currentLens: initialLens,
-      hasPermission: false,
-    };
-  }
-
-  /**
-   * @internal Called by `<UseSmileIDCameraPreview>` when the underlying
-   * `<Camera>` mounts / unmounts. Partners do not call this directly.
-   */
-  attachRef(ref: CameraInstance | null): void {
-    this._cameraRef = ref;
-  }
-
-  /** Snapshot of the runtime state. Stable across calls between updates. */
-  getState(): CameraSystemState {
-    return this._state;
-  }
-
-  /** Snapshot of the focus state. */
-  getFocusState(): FocusState {
-    return this._focusState;
-  }
-
-  /** Snapshot of the configuration last passed to `configure()`. */
-  getConfiguration(): CameraConfiguration {
-    return this._config;
-  }
-
-  /**
-   * Subscribe to state + focus-state changes. Returns an unsubscribe
-   * function; safe to call after `release()`.
-   */
-  subscribe(listener: Listener): () => void {
-    this._listeners.add(listener);
-    return () => {
-      this._listeners.delete(listener);
-    };
-  }
-
-  /**
-   * Replace the active configuration. Safe to call before `start()`;
-   * if the camera is already running, the preview reads the new lens
-   * / fps / format on its next render.
-   */
-  configure(config: CameraConfiguration): void {
-    this._config = config;
-    const lens = config.lens ?? this._state.currentLens;
-    if (lens !== this._state.currentLens) {
-      this._setState({ ...this._state, currentLens: lens });
-    }
-  }
-
-  /**
-   * Ensure permission and flip the running state on. The preview
-   * component watches `state.isCameraRunning` and `state.isStreaming`
-   * to decide when to mount the native `<Camera>` and start its frame
-   * processor.
-   *
-   * Returns once permissions have settled. The first frame can take
-   * 100–300 ms to arrive while the underlying capture session warms.
-   */
-  async start(): Promise<void> {
-    if (this._released) {
-      throw new Error(
-        "UseSmileIDCameraSystem.start called after release() — instantiate a new system",
-      );
-    }
-
-    const status = await this._ensurePermission();
-    if (status !== "granted") {
-      this._setState({ ...this._state, hasPermission: false });
-      return;
-    }
-
-    this._setState({
-      ...this._state,
-      hasPermission: true,
-      isCameraRunning: true,
-      isStreaming: true,
-    });
-  }
-
-  /**
-   * Pause the camera without tearing down the React tree. Frame
-   * processor stops firing; the preview shows the last frame.
-   * Re-callable via `start()`.
-   */
-  stop(): void {
-    if (this._released) return;
-    this._setState({
-      ...this._state,
-      isCameraRunning: false,
-      isStreaming: false,
-    });
-  }
-
-  /**
-   * Drive the focus-indicator state machine AND call vision-camera's
-   * `Camera.focus(point)` to actually re-focus the lens. The point is
-   * in normalized [0..1] preview coordinates; vision-camera converts
-   * to device coordinates internally.
-   */
-  async tapToFocus(point: FocusPoint): Promise<void> {
-    if (this._released) return;
-
-    this._setFocusState(FocusStates.running(point));
-
-    if (this._focusRunningTimeout) clearTimeout(this._focusRunningTimeout);
-    if (this._focusSettledTimeout) clearTimeout(this._focusSettledTimeout);
-
-    const ref = this._cameraRef;
-    if (ref) {
-      try {
-        await ref.focus({ x: point.x, y: point.y });
-      } catch (error) {
-        // Focus can fail on devices whose camera doesn't support
-        // programmatic focus (e.g. fixed-focus front cameras). Surface
-        // via crash reporting and keep the visual state machine
-        // moving — the user still gets reticle feedback.
-        UseSmileIDCrashReporting.captureException(error);
-      }
-    }
-
-    this._focusRunningTimeout = setTimeout(() => {
-      this._setFocusState(FocusStates.success(point));
-      this._focusSettledTimeout = setTimeout(() => {
-        this._setFocusState(FocusStates.unspecified());
-      }, CameraDefaults.focusSettledDurationMs);
-    }, CameraDefaults.focusRunningDurationMs);
-  }
-
-  /**
-   * Stop the camera, clear any focus timers, drop the ref.
-   * Idempotent — safe to call from `useEffect` cleanup.
-   *
-   * After release, calling `start()` throws — the partner must
-   * instantiate a new system.
-   */
-  release(): void {
-    this._released = true;
-    if (this._focusRunningTimeout) clearTimeout(this._focusRunningTimeout);
-    if (this._focusSettledTimeout) clearTimeout(this._focusSettledTimeout);
-    this._focusRunningTimeout = null;
-    this._focusSettledTimeout = null;
-    this._cameraRef = null;
-    this._setState({
-      ...this._state,
-      isCameraRunning: false,
-      isStreaming: false,
-    });
-  }
-
-  // --- internals -----------------------------------------------------------
-
-  private async _ensurePermission(): Promise<
-    "granted" | "denied" | "undetermined"
-  > {
-    const current = await getCameraPermissionStatus();
-    if (current === "granted") return "granted";
-    return await requestCameraPermission();
-  }
-
-  private _setState(next: CameraSystemState): void {
-    this._state = next;
-    this._notify();
-  }
-
-  private _setFocusState(next: FocusState): void {
-    this._focusState = next;
-    this._notify();
-  }
-
-  private _notify(): void {
-    for (const listener of this._listeners) {
-      try {
-        listener(this._state, this._focusState);
-      } catch {
-        /* never let a buggy listener break the dispatch chain */
-      }
-    }
-  }
-}

package/src/camera/use_smile_id_frame_stream.ts

@@ -1,189 +0,0 @@
-import { useCallback, useEffect, useMemo, useRef } from "react";
-import type {
-  DocumentAnalyzer,
-  FaceAnalyzer,
-} from "@smileid/usesmileid_platform_interface";
-import type {
-  DocumentScanResult,
-  FaceScanResult,
-} from "@smileid/usesmileid_bridge";
-import {
-  documentScanResultSchema,
-  faceScanResultSchema,
-  FrameProcessingException,
-} from "@smileid/usesmileid_bridge";
-
-/**
- * Options accepted by `useSmileIDFrameStream`. `onError` is typed
- * `unknown` — failures arrive both as Zod schema rejections and as
- * `FrameProcessingException`s; narrow with `instanceof` in the
- * callback if you need typed routing.
- */
-export type UseSmileIDFrameStreamOptions = {
-  /**
-   * Called when a frame's plugin result fails to validate or carries a
-   * native error marker. The stream keeps running — the next frame is
-   * processed normally.
-   */
-  readonly onError?: (error: unknown) => void;
-};
-
-/**
- * Return value of `useSmileIDFrameStream`. Wire `onFrameResult` into
- * the capture surface's per-frame result callback — it receives the
- * raw map the native frame processor plugin returned to the worklet.
- */
-export type UseSmileIDFrameStream = {
-  readonly onFrameResult: (rawResult: unknown) => void;
-};
-
-/**
- * Per-frame scan-result streaming hook. Pixels never reach JS — the
- * provider's native frame processor plugin hands the worklet a small
- * result map; this hook receives the raw map on the JS thread,
- * validates it against the wire schema (Zod), and routes the typed
- * result to `onResult`.
- *
- * ```tsx
- * const { onFrameResult } = useSmileIDFrameStream(faceAnalyzer, setFaceState);
- *
- * <UseSmileIDCameraPreview
- *   cameraSystem={cameraSystem}
- *   frameAnalysis={{
- *     pluginName: faceAnalyzer.frameProcessorPluginName,
- *     onResult: onFrameResult,
- *   }}
- * />;
- * ```
- *
- * Backpressure lives natively: the plugin blocks the frame-processor
- * thread per scan, so mid-scan frames are dropped before reaching JS;
- * the JS-side busy gate only guards re-entrant dispatch.
- *
- * The hook does not own the analyzer — configure / close it yourself.
- * Results arriving after unmount are dropped.
- */
-export function useSmileIDFrameStream(
-  analyzer: FaceAnalyzer | null,
-  onResult: (result: FaceScanResult) => void,
-  options?: UseSmileIDFrameStreamOptions,
-): UseSmileIDFrameStream;
-export function useSmileIDFrameStream(
-  analyzer: DocumentAnalyzer | null,
-  onResult: (result: DocumentScanResult) => void,
-  options?: UseSmileIDFrameStreamOptions,
-): UseSmileIDFrameStream;
-export function useSmileIDFrameStream(
-  analyzer: FaceAnalyzer | DocumentAnalyzer | null,
-  onResult:
-    | ((result: FaceScanResult) => void)
-    | ((result: DocumentScanResult) => void),
-  options?: UseSmileIDFrameStreamOptions,
-): UseSmileIDFrameStream {
-  const analyzerRef = useRef(analyzer);
-  const onResultRef = useRef(onResult);
-  const onErrorRef = useRef(options?.onError);
-  const busyRef = useRef(false);
-  const mountedRef = useRef(true);
-
-  useEffect(() => {
-    analyzerRef.current = analyzer;
-  }, [analyzer]);
-
-  useEffect(() => {
-    onResultRef.current = onResult;
-  }, [onResult]);
-
-  useEffect(() => {
-    onErrorRef.current = options?.onError;
-  }, [options?.onError]);
-
-  useEffect(() => {
-    mountedRef.current = true;
-    return () => {
-      mountedRef.current = false;
-    };
-  }, []);
-
-  const onFrameResult = useCallback((rawResult: unknown): void => {
-    const onError = onErrorRef.current;
-    dispatchFrameResult({
-      raw: rawResult,
-      analyzer: analyzerRef.current,
-      isBusy: () => busyRef.current,
-      setBusy: (value) => {
-        busyRef.current = value;
-      },
-      isMounted: () => mountedRef.current,
-      // Boundary cast: the overload pairing guarantees the analyzer
-      // shape matches the callback shape (face↔face / document↔document);
-      // the implementation signature widens both.
-      onResult: onResultRef.current as (
-        result: FaceScanResult | DocumentScanResult,
-      ) => void,
-      ...(onError !== undefined ? { onError } : {}),
-    });
-  }, []);
-
-  // Stable handle — an identity change here rebuilds the camera's
-  // frame processor, so memoise.
-  return useMemo(() => ({ onFrameResult }), [onFrameResult]);
-}
-
-/**
- * Extract the error marker, if present — native plugins signal
- * frame-level failures by returning `{ error: "<reason>" }` instead of
- * a scan-result map.
- */
-function readPluginError(raw: unknown): string | null {
-  if (raw === null || typeof raw !== "object") return null;
-  // Boundary cast: `raw` crossed the worklet bridge as `unknown`; the
-  // key's type is verified before use.
-  const reason = (raw as Record<string, unknown>)["error"];
-  return typeof reason === "string" ? reason : null;
-}
-
-/**
- * Pure dispatch logic extracted from the hook so vitest can exercise
- * the busy-gate, mounted-gate, error-marker, and schema-validation
- * branches without standing up a React renderer.
- *
- * @internal
- */
-export function dispatchFrameResult(args: {
-  /** Raw value the native frame processor plugin returned to the worklet. */
-  readonly raw: unknown;
-  readonly analyzer:
-    | Pick<FaceAnalyzer, "kind">
-    | Pick<DocumentAnalyzer, "kind">
-    | null;
-  readonly isBusy: () => boolean;
-  readonly setBusy: (value: boolean) => void;
-  readonly isMounted: () => boolean;
-  readonly onResult: (result: FaceScanResult | DocumentScanResult) => void;
-  readonly onError?: (error: unknown) => void;
-}): void {
-  const { raw, analyzer, isBusy, setBusy, isMounted, onResult, onError } = args;
-
-  if (!analyzer) return;
-  if (isBusy()) return;
-
-  setBusy(true);
-  try {
-    const errorReason = readPluginError(raw);
-    if (errorReason !== null) {
-      throw new FrameProcessingException({ reason: errorReason });
-    }
-    const result =
-      analyzer.kind === "face"
-        ? faceScanResultSchema.parse(raw)
-        : documentScanResultSchema.parse(raw);
-    if (!isMounted()) return;
-    onResult(result);
-  } catch (error) {
-    if (!isMounted()) return;
-    onError?.(error);
-  } finally {
-    setBusy(false);
-  }
-}