@velion-la/onboarding-sdk-react-native 1.2.0-beta.1 → 1.2.0-beta.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/README.md +15 -13
  2. package/lib/commonjs/camera/DocumentCapture.js +53 -33
  3. package/lib/commonjs/camera/DocumentCapture.js.map +1 -1
  4. package/lib/commonjs/camera/LivenessCamera.js +120 -83
  5. package/lib/commonjs/camera/LivenessCamera.js.map +1 -1
  6. package/lib/commonjs/camera/MapAddressPicker.js +1 -1
  7. package/lib/commonjs/camera/MapAddressPicker.js.map +1 -1
  8. package/lib/commonjs/steps/DocumentsOcrStep.js +2 -2
  9. package/lib/commonjs/steps/DocumentsOcrStep.js.map +1 -1
  10. package/lib/commonjs/steps/LivenessMatchStep.js +7 -4
  11. package/lib/commonjs/steps/LivenessMatchStep.js.map +1 -1
  12. package/lib/commonjs/ui/overlays/LoadingOverlay.js +1 -1
  13. package/lib/commonjs/ui/overlays/LoadingOverlay.js.map +1 -1
  14. package/lib/commonjs/ui/overlays/RetryDialog.js +1 -1
  15. package/lib/commonjs/ui/overlays/RetryDialog.js.map +1 -1
  16. package/lib/module/camera/DocumentCapture.js +54 -34
  17. package/lib/module/camera/DocumentCapture.js.map +1 -1
  18. package/lib/module/camera/LivenessCamera.js +121 -84
  19. package/lib/module/camera/LivenessCamera.js.map +1 -1
  20. package/lib/module/camera/MapAddressPicker.js +1 -1
  21. package/lib/module/camera/MapAddressPicker.js.map +1 -1
  22. package/lib/module/steps/DocumentsOcrStep.js +2 -2
  23. package/lib/module/steps/DocumentsOcrStep.js.map +1 -1
  24. package/lib/module/steps/LivenessMatchStep.js +7 -4
  25. package/lib/module/steps/LivenessMatchStep.js.map +1 -1
  26. package/lib/module/ui/overlays/LoadingOverlay.js +1 -1
  27. package/lib/module/ui/overlays/LoadingOverlay.js.map +1 -1
  28. package/lib/module/ui/overlays/RetryDialog.js +1 -1
  29. package/lib/module/ui/overlays/RetryDialog.js.map +1 -1
  30. package/lib/typescript/camera/DocumentCapture.d.ts +9 -3
  31. package/lib/typescript/camera/DocumentCapture.d.ts.map +1 -1
  32. package/lib/typescript/camera/LivenessCamera.d.ts +27 -9
  33. package/lib/typescript/camera/LivenessCamera.d.ts.map +1 -1
  34. package/lib/typescript/steps/LivenessMatchStep.d.ts.map +1 -1
  35. package/package.json +16 -14
  36. package/src/camera/DocumentCapture.tsx +56 -39
  37. package/src/camera/LivenessCamera.tsx +140 -83
  38. package/src/camera/MapAddressPicker.tsx +1 -1
  39. package/src/steps/DocumentsOcrStep.tsx +2 -2
  40. package/src/steps/LivenessMatchStep.tsx +12 -6
  41. package/src/ui/overlays/LoadingOverlay.tsx +1 -1
  42. package/src/ui/overlays/RetryDialog.tsx +1 -1
@@ -2,18 +2,36 @@
2
2
  * @fileoverview Liveness camera surface — front-facing vision-camera with an
3
3
  * oval mask, status pill, and capture loop driven by the parent step.
4
4
  *
5
- * Capture strategy: vision-camera v4 frame processors run on a worklet thread
6
- * and don't expose the JPEG bytes back to JS without a custom native plugin.
7
- * We avoid that complication by using `takePhoto({ qualityPrioritization:
8
- * 'speed' })` on a JS-level interval (matches the `setInterval` pattern in
9
- * `web/LivenessModule.ts`). Real-world FPS lands around 3–8 fps which is
10
- * sufficient for Iris's challenge cadence.
5
+ * Capture strategy: frame processors run on a worklet thread and don't expose
6
+ * the JPEG bytes back to JS without a custom native plugin. We avoid that
7
+ * complication by capturing stills to a file on a JS-level interval (matches
8
+ * the `setInterval` pattern in `web/LivenessModule.ts`). Real-world FPS lands
9
+ * around 3–8 fps which is sufficient for Iris's challenge cadence.
10
+ *
11
+ * The camera streams into three outputs at once — preview, photo and video —
12
+ * so the frames sent to Iris and the mp4 kept as evidence come off the same
13
+ * session without either interrupting the other.
11
14
  *
12
15
  * The parent owns the loop and the WebSocket — this component just exposes a
13
16
  * `captureFrame` ref so the step can drive the timing while the camera stays
14
17
  * mounted across challenges.
15
18
  */
16
- import { type PhotoFile, type VideoFile } from 'react-native-vision-camera';
19
+ import { type PhotoFile } from 'react-native-vision-camera';
20
+ /**
21
+ * The recorded liveness video, as this component reports it upwards.
22
+ *
23
+ * vision-camera v5 hands `onRecordingFinished` a bare file path, while the
24
+ * upload pipeline also wants the duration for the `liveness-verify` metadata.
25
+ * We read the duration off the `Recorder` before finalising and re-assemble
26
+ * both here, so the step keeps consuming one object instead of two loose
27
+ * values.
28
+ */
29
+ export interface LivenessVideoFile {
30
+ /** Filesystem path, not a `file://` URL. */
31
+ path: string;
32
+ /** Recorded duration in seconds, or `undefined` when it could not be read. */
33
+ duration?: number | undefined;
34
+ }
17
35
  export interface LivenessCameraHandle {
18
36
  takeFrame: () => Promise<PhotoFile | null>;
19
37
  /**
@@ -24,9 +42,9 @@ export interface LivenessCameraHandle {
24
42
  * even when this fails.
25
43
  */
26
44
  startVideoRecording(opts: {
27
- onRecordingFinished: (video: VideoFile) => void;
45
+ onRecordingFinished: (video: LivenessVideoFile) => void;
28
46
  onRecordingError: (err: unknown) => void;
29
- }): void;
47
+ }): Promise<void>;
30
48
  /**
31
49
  * Stop the active recording. Resolves once `onRecordingFinished` has been
32
50
  * scheduled by vision-camera; the file path arrives there, not here.
@@ -1 +1 @@
1
- {"version":3,"file":"LivenessCamera.d.ts","sourceRoot":"","sources":["../../../src/camera/LivenessCamera.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAoBH,OAAO,EAKL,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,4BAA4B,CAAC;AAKpC,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAC3C;;;;;;OAMG;IACH,mBAAmB,CAAC,IAAI,EAAE;QACxB,mBAAmB,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;QAChD,gBAAgB,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;KAC1C,GAAG,IAAI,CAAC;IACT;;;;OAIG;IACH,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,aAAa,GAAG,cAAc,CAAC;AAEzE,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC1C,2EAA2E;IAC3E,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IACtC,iFAAiF;IACjF,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,GAAG,SAAS,CAAC;IAC5E,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACrC,wCAAwC;IACxC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;CACrC;AAED,eAAO,MAAM,cAAc,sHAgP1B,CAAC"}
1
+ {"version":3,"file":"LivenessCamera.d.ts","sourceRoot":"","sources":["../../../src/camera/LivenessCamera.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAoBH,OAAO,EASL,KAAK,SAAS,EAEf,MAAM,4BAA4B,CAAC;AAKpC;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAC3C;;;;;;OAMG;IACH,mBAAmB,CAAC,IAAI,EAAE;QACxB,mBAAmB,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;QACxD,gBAAgB,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;KAC1C,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClB;;;;OAIG;IACH,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,aAAa,GAAG,cAAc,CAAC;AAEzE,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC1C,2EAA2E;IAC3E,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IACtC,iFAAiF;IACjF,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,GAAG,SAAS,CAAC;IAC5E,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACrC,wCAAwC;IACxC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;CACrC;AAED,eAAO,MAAM,cAAc,sHAkR1B,CAAC"}
@@ -1 +1 @@
1
- {"version":3,"file":"LivenessMatchStep.d.ts","sourceRoot":"","sources":["../../../src/steps/LivenessMatchStep.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAiDH,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAwCpD,qBAAa,iBAAkB,YAAW,UAAU;IAKtC,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJjC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,SAAS,CAAS;gBAEG,IAAI,EAAE,QAAQ;IAE3C,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IA4BpB,OAAO,IAAI,IAAI;CAIhB"}
1
+ {"version":3,"file":"LivenessMatchStep.d.ts","sourceRoot":"","sources":["../../../src/steps/LivenessMatchStep.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAkDH,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAwCpD,qBAAa,iBAAkB,YAAW,UAAU;IAKtC,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJjC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,SAAS,CAAS;gBAEG,IAAI,EAAE,QAAQ;IAE3C,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IA4BpB,OAAO,IAAI,IAAI;CAIhB"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@velion-la/onboarding-sdk-react-native",
3
- "version": "1.2.0-beta.1",
3
+ "version": "1.2.0-beta.4",
4
4
  "description": "Native React Native SDK for the Velion Onboarding (KYC) flow: ID document OCR, passive + active liveness, device fingerprint, OTP verification, address picker, and personal / legal information forms.",
5
5
  "main": "./lib/commonjs/index.js",
6
6
  "module": "./lib/module/index.js",
@@ -58,26 +58,28 @@
58
58
  },
59
59
  "dependencies": {
60
60
  "@noble/hashes": "^1.5.0",
61
- "expo-application": "~7.0.0",
62
- "expo-constants": "~18.0.0",
63
- "expo-crypto": "~15.0.0",
64
- "expo-device": "~8.0.0",
65
- "expo-file-system": "~19.0.0",
66
- "expo-image-manipulator": "~14.0.0",
67
- "expo-keep-awake": "~15.0.0",
68
- "expo-location": "~19.0.0",
61
+ "expo-application": "~57.0.2",
62
+ "expo-constants": "~57.0.17",
63
+ "expo-crypto": "~57.0.2",
64
+ "expo-device": "~57.0.1",
65
+ "expo-file-system": "~57.0.6",
66
+ "expo-image-manipulator": "~57.0.16",
67
+ "expo-keep-awake": "~57.0.1",
68
+ "expo-location": "~57.0.16",
69
69
  "react-native-sse": "^1.2.1"
70
70
  },
71
71
  "peerDependencies": {
72
72
  "@fingerprintjs/fingerprintjs-pro-react-native": ">=3.0.0",
73
- "expo": ">=54.0.0",
74
- "react": ">=19.0.0",
75
- "react-native": ">=0.81.0",
73
+ "expo": ">=57.0.0",
74
+ "react": ">=19.2.0",
75
+ "react-native": ">=0.86.0",
76
76
  "react-native-keyboard-controller": ">=1.18.0",
77
77
  "react-native-maps": ">=1.20.0",
78
+ "react-native-nitro-image": ">=0.15.0",
79
+ "react-native-nitro-modules": ">=0.37.0",
78
80
  "react-native-safe-area-context": ">=4.0.0",
79
81
  "react-native-svg": ">=15.0.0",
80
- "react-native-vision-camera": ">=4.6.0"
82
+ "react-native-vision-camera": ">=5.0.0"
81
83
  },
82
84
  "peerDependenciesMeta": {
83
85
  "@fingerprintjs/fingerprintjs-pro-react-native": {
@@ -92,7 +94,7 @@
92
94
  },
93
95
  "devDependencies": {
94
96
  "@types/jest": "^29.5.12",
95
- "@types/react": "~19.1.0",
97
+ "@types/react": "~19.2.0",
96
98
  "del-cli": "^6.0.0",
97
99
  "jest": "^29.7.0",
98
100
  "react-native-builder-bob": "^0.40.0",
@@ -1,9 +1,15 @@
1
1
  /**
2
2
  * @fileoverview Full-screen document camera with an ID-1 frame guide.
3
3
  *
4
- * Uses `react-native-vision-camera` v4 in `photo` mode. Tapping the shutter
5
- * triggers `takePhoto()` with `qualityPrioritization: 'balanced'`; the file
6
- * URI is returned to the caller via `onCaptured`.
4
+ * Uses `react-native-vision-camera` v5. The camera streams into two explicit
5
+ * outputs — a preview and a photo output configured for `quality` — and the
6
+ * shutter calls `capturePhotoToFile()`, which writes the JPEG to a temporary
7
+ * file and hands its path to the caller via `onCaptured`.
8
+ *
9
+ * We deliberately use `capturePhotoToFile()` rather than `capturePhoto()`:
10
+ * the caller only ever needs a path to crop and upload, and the file variant
11
+ * avoids holding a native `Photo` buffer in JS that would have to be
12
+ * `dispose()`d by hand on every branch, including the error paths.
7
13
  *
8
14
  * Visual: dark scrim with a transparent rectangular cutout (ID-1 ratio). The
9
15
  * cutout is both the visible guide AND the crop region: on capture we hand the
@@ -27,6 +33,9 @@ import {
27
33
  Camera,
28
34
  useCameraDevice,
29
35
  useCameraPermission,
36
+ usePhotoOutput,
37
+ usePreviewOutput,
38
+ type CameraRef,
30
39
  type PhotoFile,
31
40
  } from 'react-native-vision-camera';
32
41
  import type { DocumentOrientation, DocumentSide } from '../types';
@@ -83,7 +92,15 @@ export function DocumentCapture({
83
92
  const theme = useTheme();
84
93
  const insets = useSafeAreaInsets();
85
94
  const { width: screenW, height: screenH } = useWindowDimensions();
86
- const cameraRef = useRef<Camera>(null);
95
+ const cameraRef = useRef<CameraRef>(null);
96
+ // The preview the user frames the document in, and the still-image output
97
+ // the shutter captures from. In v5 both are explicit: the session only
98
+ // produces what the `outputs` array asks for.
99
+ const previewOutput = usePreviewOutput();
100
+ // `quality` over speed — this frame goes to the backend OCR, and a soft or
101
+ // over-compressed capture is the difference between a readable document and
102
+ // a rejected one. The default `UHD_4_3` target resolution is kept.
103
+ const photoOutput = usePhotoOutput({ qualityPrioritization: 'quality' });
87
104
  // Cross-platform back-camera selection.
88
105
  //
89
106
  // iOS (especially 15 Pro / Pro Max with multi-lens systems): asking for
@@ -100,11 +117,7 @@ export function DocumentCapture({
100
117
  // harm anything. Continuous AF is the default focus mode on both
101
118
  // platforms, so cross-platform behaviour stays consistent.
102
119
  const device = useCameraDevice('back', {
103
- physicalDevices: [
104
- 'ultra-wide-angle-camera',
105
- 'wide-angle-camera',
106
- 'telephoto-camera',
107
- ],
120
+ physicalDevices: ['ultra-wide-angle', 'wide-angle', 'telephoto'],
108
121
  });
109
122
  const { hasPermission, requestPermission } = useCameraPermission();
110
123
  const [requestedOnce, setRequestedOnce] = useState(false);
@@ -134,25 +147,30 @@ export function DocumentCapture({
134
147
  return () => clearTimeout(t);
135
148
  }, [device, hasPermission]);
136
149
 
137
- // NOTE: we intentionally do NOT call `cameraRef.current.focus()` on mount
138
- // or before each shutter. iOS's continuous auto-focus runs by default and
139
- // is what makes the native Camera app feel sharp at any distance. Calling
140
- // `focus()` switches the device into single-shot/locked mode and DOES NOT
141
- // restore continuous AF afterwards (vision-camera v4 has no "resume AF"
142
- // API). The previous "autofocus on mount" + "autofocus before shutter"
143
- // calls were the cause of blurry captures on iPhone 15 Pro Max: they
144
- // pinned focus to the centre even after the user moved the phone, and
145
- // never re-engaged continuous AF.
150
+ // NOTE: we intentionally do NOT call `focusTo()` on mount or before each
151
+ // shutter. iOS's continuous auto-focus runs by default and is what makes
152
+ // the native Camera app feel sharp at any distance. Focusing explicitly
153
+ // switches the device into single-shot/locked mode and does not restore
154
+ // continuous AF on its own. The previous "autofocus on mount" + "autofocus
155
+ // before shutter" calls were the cause of blurry captures on iPhone 15 Pro
156
+ // Max: they pinned focus to the centre even after the user moved the phone,
157
+ // and never re-engaged continuous AF.
158
+ //
159
+ // v5 does expose `CameraRef.resetFocus()` to return the device to
160
+ // continuous AF, but we deliberately don't call it after a tap: the tap is
161
+ // the user asking us to hold focus there, and auto-releasing it would fight
162
+ // that intent. Focus re-engages when the component remounts for the next
163
+ // side of the document.
146
164
  //
147
165
  // Tap-to-focus is the one user-initiated override — when the user taps,
148
166
  // they're explicitly asking us to lock focus on that point.
149
- const supportsFocus = Boolean(device?.supportsFocus);
167
+ const supportsFocus = Boolean(device?.supportsFocusMetering);
150
168
 
151
169
  const handleTapToFocus = useCallback(
152
170
  (event: { nativeEvent: { locationX: number; locationY: number } }) => {
153
171
  if (!supportsFocus || !cameraRef.current) return;
154
172
  const { locationX, locationY } = event.nativeEvent;
155
- cameraRef.current.focus({ x: locationX, y: locationY }).catch(() => {
173
+ cameraRef.current.focusTo({ x: locationX, y: locationY }).catch(() => {
156
174
  // Ignore — focus rejection is non-fatal.
157
175
  });
158
176
  setFocusPoint({ x: locationX, y: locationY, key: Date.now() });
@@ -172,10 +190,10 @@ export function DocumentCapture({
172
190
  setShooting(true);
173
191
  setError(null);
174
192
  try {
175
- const photo = await cameraRef.current.takePhoto({
176
- flash: 'off',
177
- enableShutterSound: false,
178
- });
193
+ const photo = await photoOutput.capturePhotoToFile(
194
+ { flashMode: 'off', enableShutterSound: false },
195
+ {},
196
+ );
179
197
  // Await the caller's crop/compress so the processing overlay stays up
180
198
  // for the whole capture→preview gap (a few seconds), giving the user
181
199
  // feedback instead of an idle camera. On success the parent flips phase
@@ -188,7 +206,7 @@ export function DocumentCapture({
188
206
  } finally {
189
207
  setShooting(false);
190
208
  }
191
- }, [onCaptured, side, shooting, orientation, screenW, screenH]);
209
+ }, [onCaptured, photoOutput, side, shooting, orientation, screenW, screenH]);
192
210
 
193
211
  if (!hasPermission) {
194
212
  return (
@@ -250,24 +268,23 @@ export function DocumentCapture({
250
268
  ref={cameraRef}
251
269
  style={StyleSheet.absoluteFill}
252
270
  device={device}
253
- photo
254
- photoQualityBalance="quality"
255
- // Lock the captured photo to the *preview's* orientation (OSDKR-13).
256
- // vision-camera defaults to `outputOrientation="device"`, which emits
257
- // the photo in whatever orientation the phone is physically held —
258
- // even though this screen is locked to portrait and both the preview
259
- // and the ID-1 guide stay portrait. A user tilting the phone sideways
260
- // to frame a landscape card therefore got a photo rotated 90° from
261
- // what they framed, and the guide→photo crop mapping (which is in
262
- // screen space) landed on the wrong region. With `preview` the photo
263
- // always comes back in the orientation the user saw.
264
- outputOrientation="preview"
271
+ outputs={[previewOutput, photoOutput]}
272
+ // Lock the captured photo to the *interface* orientation (OSDKR-13).
273
+ // The alternative, `'device'`, emits the photo in whatever orientation
274
+ // the phone is physically held — even though this screen is locked to
275
+ // portrait and both the preview and the ID-1 guide stay portrait. A
276
+ // user tilting the phone sideways to frame a landscape card therefore
277
+ // got a photo rotated 90° from what they framed, and the guide→photo
278
+ // crop mapping (which is in screen space) landed on the wrong region.
279
+ // With `'interface'` the photo always comes back in the orientation
280
+ // the user saw. (This is v5's spelling of what v4 called
281
+ // `outputOrientation="preview"`.)
282
+ orientationSource="interface"
265
283
  // Explicit `cover`: the guide-crop math in `computeGuideCropRect`
266
284
  // assumes the preview center-crops the sensor frame to the screen
267
285
  // aspect ratio. `cover` is vision-camera's default, but we pin it so
268
286
  // the crop never silently drifts if that default changes.
269
287
  resizeMode="cover"
270
- enableZoomGesture={false}
271
288
  isActive
272
289
  />
273
290
  {/* Invisible pressable layer over the camera preview for tap-to-focus.
@@ -550,7 +567,7 @@ const styles = StyleSheet.create({
550
567
  backgroundColor: 'transparent',
551
568
  },
552
569
  processingOverlay: {
553
- ...StyleSheet.absoluteFillObject,
570
+ ...StyleSheet.absoluteFill,
554
571
  alignItems: 'center',
555
572
  justifyContent: 'center',
556
573
  gap: 14,
@@ -2,12 +2,15 @@
2
2
  * @fileoverview Liveness camera surface — front-facing vision-camera with an
3
3
  * oval mask, status pill, and capture loop driven by the parent step.
4
4
  *
5
- * Capture strategy: vision-camera v4 frame processors run on a worklet thread
6
- * and don't expose the JPEG bytes back to JS without a custom native plugin.
7
- * We avoid that complication by using `takePhoto({ qualityPrioritization:
8
- * 'speed' })` on a JS-level interval (matches the `setInterval` pattern in
9
- * `web/LivenessModule.ts`). Real-world FPS lands around 3–8 fps which is
10
- * sufficient for Iris's challenge cadence.
5
+ * Capture strategy: frame processors run on a worklet thread and don't expose
6
+ * the JPEG bytes back to JS without a custom native plugin. We avoid that
7
+ * complication by capturing stills to a file on a JS-level interval (matches
8
+ * the `setInterval` pattern in `web/LivenessModule.ts`). Real-world FPS lands
9
+ * around 3–8 fps which is sufficient for Iris's challenge cadence.
10
+ *
11
+ * The camera streams into three outputs at once — preview, photo and video —
12
+ * so the frames sent to Iris and the mp4 kept as evidence come off the same
13
+ * session without either interrupting the other.
11
14
  *
12
15
  * The parent owns the loop and the WebSocket — this component just exposes a
13
16
  * `captureFrame` ref so the step can drive the timing while the camera stays
@@ -34,16 +37,36 @@ import {
34
37
  import Svg, { Defs, Ellipse, Mask, Rect } from 'react-native-svg';
35
38
  import {
36
39
  Camera,
40
+ CommonResolutions,
37
41
  useCameraDevice,
38
- useCameraFormat,
39
42
  useCameraPermission,
43
+ usePhotoOutput,
44
+ usePreviewOutput,
45
+ useVideoOutput,
46
+ type CameraRef,
40
47
  type PhotoFile,
41
- type VideoFile,
48
+ type Recorder,
42
49
  } from 'react-native-vision-camera';
43
50
  import { Button } from '../ui/primitives/Button';
44
51
  import { useTheme, withAlpha } from '../ui/theme';
45
52
  import { useSafeAreaInsets } from '../utils/useSafeAreaInsets';
46
53
 
54
+ /**
55
+ * The recorded liveness video, as this component reports it upwards.
56
+ *
57
+ * vision-camera v5 hands `onRecordingFinished` a bare file path, while the
58
+ * upload pipeline also wants the duration for the `liveness-verify` metadata.
59
+ * We read the duration off the `Recorder` before finalising and re-assemble
60
+ * both here, so the step keeps consuming one object instead of two loose
61
+ * values.
62
+ */
63
+ export interface LivenessVideoFile {
64
+ /** Filesystem path, not a `file://` URL. */
65
+ path: string;
66
+ /** Recorded duration in seconds, or `undefined` when it could not be read. */
67
+ duration?: number | undefined;
68
+ }
69
+
47
70
  export interface LivenessCameraHandle {
48
71
  takeFrame: () => Promise<PhotoFile | null>;
49
72
  /**
@@ -54,9 +77,9 @@ export interface LivenessCameraHandle {
54
77
  * even when this fails.
55
78
  */
56
79
  startVideoRecording(opts: {
57
- onRecordingFinished: (video: VideoFile) => void;
80
+ onRecordingFinished: (video: LivenessVideoFile) => void;
58
81
  onRecordingError: (err: unknown) => void;
59
- }): void;
82
+ }): Promise<void>;
60
83
  /**
61
84
  * Stop the active recording. Resolves once `onRecordingFinished` has been
62
85
  * scheduled by vision-camera; the file path arrives there, not here.
@@ -97,18 +120,29 @@ export const LivenessCamera = forwardRef<LivenessCameraHandle, LivenessCameraPro
97
120
  function LivenessCamera(props, ref) {
98
121
  const theme = useTheme();
99
122
  const insets = useSafeAreaInsets();
100
- const cameraRef = useRef<Camera>(null);
123
+ const cameraRef = useRef<CameraRef>(null);
101
124
  const device = useCameraDevice('front');
102
- // Pick a 720p / 30-fps format so the recorded mp4 stays a few MB instead
103
- // of the device-default 1080p–4K bitrate (a 30 s session can otherwise
104
- // produce a 50–80 MB file that times out on mobile uplinks). The face
105
- // visibility for liveness evidence is fine at 720p. Constraints are
106
- // ordered by priority — vision-camera picks the closest match.
107
- const format = useCameraFormat(device, [
108
- { videoResolution: { width: 1280, height: 720 } },
109
- { fps: 30 },
110
- { videoStabilizationMode: 'off' },
111
- ]);
125
+ const previewOutput = usePreviewOutput();
126
+ // Frames for Iris: `speed` over quality on purpose. These are downscaled
127
+ // and re-compressed by `ImageManipulator` before they ever reach the wire,
128
+ // so a slow high-fidelity capture would only cost us frame cadence.
129
+ const photoOutput = usePhotoOutput({ qualityPrioritization: 'speed' });
130
+ // Pin the recording to 720p so the mp4 stays a few MB instead of the
131
+ // device-default 1080p–4K bitrate (a 30 s session can otherwise produce a
132
+ // 50–80 MB file that times out on mobile uplinks). Face visibility for
133
+ // liveness evidence is fine at 720p. Audio off — the backend never uses it
134
+ // and recording it would demand the microphone permission.
135
+ const videoOutput = useVideoOutput({
136
+ targetResolution: CommonResolutions.HD_16_9,
137
+ // ~2 Mbps. NOTE the unit: v5 takes bits per second, where v4's
138
+ // `videoBitRate` prop took megabits — passing `2` here would ask for
139
+ // 2 bps and produce an unusable file. The device default (~8 Mbps at
140
+ // 720p) yields a 38 MB file for a 30 s session; ~2 Mbps is plenty for
141
+ // face visibility as compliance evidence and lands around 7–8 MB.
142
+ targetBitRate: 2_000_000,
143
+ enableAudio: false,
144
+ fileType: 'mp4',
145
+ });
112
146
  const { hasPermission, requestPermission } = useCameraPermission();
113
147
  const requestedRef = useRef(false);
114
148
  const inFlightRef = useRef(false);
@@ -132,16 +166,23 @@ export const LivenessCamera = forwardRef<LivenessCameraHandle, LivenessCameraPro
132
166
  return () => clearTimeout(t);
133
167
  }, [device, hasPermission]);
134
168
 
169
+ // NOTE: `capturePhotoToFile`, not `capturePhoto`. The in-memory variant
170
+ // would hand us a native `Photo` that must be `dispose()`d by hand — in a
171
+ // loop running at up to ~7 fps for a whole session, a single missed
172
+ // dispose on an error path leaks native buffers. It would only pay off if
173
+ // we could sign the bytes directly, and we cannot: the frame still has to
174
+ // go through `ImageManipulator` for the downscale and the horizontal flip,
175
+ // and that API takes a URI, not a buffer. So the file is needed either
176
+ // way, and capturing straight to one keeps the hot loop free of manual
177
+ // memory management.
135
178
  const takeFrame = useCallback(async (): Promise<PhotoFile | null> => {
136
179
  if (inFlightRef.current) return null;
137
- const camera = cameraRef.current;
138
- if (!camera) return null;
139
180
  inFlightRef.current = true;
140
181
  try {
141
- return await camera.takePhoto({
142
- flash: 'off',
143
- enableShutterSound: false,
144
- });
182
+ return await photoOutput.capturePhotoToFile(
183
+ { flashMode: 'off', enableShutterSound: false },
184
+ {},
185
+ );
145
186
  } catch {
146
187
  // Frame failures are non-fatal — the parent loop just retries on the
147
188
  // next tick. Keep the camera mounted.
@@ -149,47 +190,71 @@ export const LivenessCamera = forwardRef<LivenessCameraHandle, LivenessCameraPro
149
190
  } finally {
150
191
  inFlightRef.current = false;
151
192
  }
152
- }, []);
193
+ }, [photoOutput]);
153
194
 
154
- // Recording is best-effort and orthogonal to the frame loop. We track an
155
- // `isRecording` flag so `stopVideoRecording` is idempotent even if the
156
- // parent calls it twice (e.g. on SESSION_COMPLETE and again on unmount).
157
- const recordingRef = useRef(false);
195
+ // Recording is best-effort and orthogonal to the frame loop. We keep the
196
+ // live `Recorder` in a ref so `stopVideoRecording` is idempotent even if
197
+ // the parent calls it twice (e.g. on SESSION_COMPLETE and again on
198
+ // unmount). In v5 a Recorder is single-use: one is created per recording
199
+ // and discarded once it finishes.
200
+ const recorderRef = useRef<Recorder | null>(null);
201
+ // Duration read off the Recorder just before finalising. v5's
202
+ // `onRecordingFinished` only carries the file path, but the upload
203
+ // pipeline reports the duration in the `liveness-verify` metadata.
204
+ const recordedDurationRef = useRef<number | undefined>(undefined);
158
205
 
159
206
  const startVideoRecording = useCallback(
160
- (opts: {
161
- onRecordingFinished: (video: VideoFile) => void;
207
+ async (opts: {
208
+ onRecordingFinished: (video: LivenessVideoFile) => void;
162
209
  onRecordingError: (err: unknown) => void;
163
- }) => {
164
- const camera = cameraRef.current;
165
- if (!camera) {
166
- throw new Error('Camera is not mounted; cannot start recording.');
210
+ }): Promise<void> => {
211
+ if (recorderRef.current) return;
212
+ const recorder = await videoOutput.createRecorder({});
213
+ recorderRef.current = recorder;
214
+ recordedDurationRef.current = undefined;
215
+ try {
216
+ await recorder.startRecording(
217
+ (filePath) => {
218
+ const duration =
219
+ recordedDurationRef.current ??
220
+ (typeof recorder.recordedDuration === 'number'
221
+ ? recorder.recordedDuration
222
+ : undefined);
223
+ recorderRef.current = null;
224
+ opts.onRecordingFinished({ path: filePath, duration });
225
+ },
226
+ (error) => {
227
+ recorderRef.current = null;
228
+ opts.onRecordingError(error);
229
+ },
230
+ );
231
+ } catch (err) {
232
+ // Startup failed, so neither callback will ever fire — release the
233
+ // ref here or every later start would short-circuit on it.
234
+ recorderRef.current = null;
235
+ throw err;
167
236
  }
168
- if (recordingRef.current) return;
169
- recordingRef.current = true;
170
- camera.startRecording({
171
- fileType: 'mp4',
172
- videoCodec: 'h264',
173
- flash: 'off',
174
- onRecordingFinished: (video) => {
175
- recordingRef.current = false;
176
- opts.onRecordingFinished(video);
177
- },
178
- onRecordingError: (err) => {
179
- recordingRef.current = false;
180
- opts.onRecordingError(err);
181
- },
182
- });
183
237
  },
184
- [],
238
+ [videoOutput],
185
239
  );
186
240
 
187
241
  const stopVideoRecording = useCallback(async (): Promise<void> => {
188
- const camera = cameraRef.current;
189
- if (!camera || !recordingRef.current) return;
190
- await camera.stopRecording();
191
- // recordingRef is cleared inside onRecordingFinished/onRecordingError to
192
- // avoid a window where a follow-up start() races with the unfinished stop.
242
+ const recorder = recorderRef.current;
243
+ if (!recorder) return;
244
+ // Read the duration BEFORE stopping: once the recording is finalised the
245
+ // counter is no longer meaningful, and `onRecordingFinished` does not
246
+ // carry it.
247
+ try {
248
+ recordedDurationRef.current =
249
+ typeof recorder.recordedDuration === 'number'
250
+ ? recorder.recordedDuration
251
+ : undefined;
252
+ } catch {
253
+ recordedDurationRef.current = undefined;
254
+ }
255
+ await recorder.stopRecording();
256
+ // recorderRef is cleared inside onRecordingFinished/onRecordingError to
257
+ // avoid a window where a follow-up start races with the unfinished stop.
193
258
  }, []);
194
259
 
195
260
  useImperativeHandle(
@@ -263,30 +328,22 @@ export const LivenessCamera = forwardRef<LivenessCameraHandle, LivenessCameraPro
263
328
  ref={cameraRef}
264
329
  style={StyleSheet.absoluteFill}
265
330
  device={device}
266
- // `format` and `fps` cap the sensor output to 720p / 30 fps so the
267
- // recorded mp4 lands in the few-MB range instead of the device
268
- // default (which on modern iPhones is 1080p–4K @ 60 fps).
269
- {...(format ? { format } : {})}
270
- fps={30}
271
- // Cap the encoder to ~2 Mbps. The default `'normal'` setting maps
272
- // to ~8 Mbps for 720p, producing a 38 MB file for a 30 s session;
273
- // ~2 Mbps is plenty for face visibility (compliance evidence) and
274
- // keeps a 30 s recording around 7-8 MB.
275
- videoBitRate={2}
276
- // Lock the recorded video orientation to the preview view's so it
277
- // is never upside-down or sideways on the back-office player.
278
- outputOrientation="preview"
279
- photo
280
- // Enable mp4/h264 recording in parallel with takePhoto(). vision-camera
281
- // v4 supports both surfaces on the same <Camera>; the recording runs
282
- // best-effort and does not affect the frame cadence sent to Iris.
283
- video
284
- audio={false}
285
- photoQualityBalance="speed"
286
- // Keep the vision-camera default (`isMirrored=true` for front cam):
287
- // overriding it to `false` causes a v4 iOS bug where the tkhd matrix
288
- // is written rotated −90° instead of +90°, leaving the recorded mp4
289
- // upside-down. The JPEG frames we send to Iris are un-mirrored
331
+ // Preview, frames for Iris, and the mp4 recording all stream off the
332
+ // same session. This is the capability the whole liveness step rests
333
+ // on: the JPEG frames and the evidence video are produced at once,
334
+ // from one camera, without interrupting either.
335
+ outputs={[previewOutput, photoOutput, videoOutput]}
336
+ // Cap the sensor at 30 fps. Resolution and bit-rate are set on the
337
+ // video output itself (see `useVideoOutput` above).
338
+ constraints={[{ fps: 30 }]}
339
+ // Lock the recorded video orientation to the interface's so it is
340
+ // never upside-down or sideways on the back-office player. (v5's
341
+ // spelling of what v4 called `outputOrientation="preview"`.)
342
+ orientationSource="interface"
343
+ // We keep the front camera's default mirroring rather than forcing
344
+ // `isMirrored=false`: in v4 that override triggered an iOS bug where
345
+ // the tkhd matrix was written rotated −90° instead of +90°, leaving
346
+ // the mp4 upside-down. The frames we send to Iris are un-mirrored
290
347
  // separately in `captureAndSend` via a horizontal flip with
291
348
  // expo-image-manipulator, so TURN_LEFT/RIGHT still maps to the
292
349
  // real-world yaw.
@@ -356,7 +356,7 @@ const styles = StyleSheet.create({
356
356
  // so any backdrop colour would only show briefly while tiles are loading.
357
357
  },
358
358
  mapLoading: {
359
- ...StyleSheet.absoluteFillObject,
359
+ ...StyleSheet.absoluteFill,
360
360
  alignItems: 'center',
361
361
  justifyContent: 'center',
362
362
  },
@@ -170,7 +170,7 @@ function DocumentsOcrView({
170
170
  const handleCaptured = useCallback(
171
171
  async (photo: PhotoFile, side: DocumentSide, guide: CaptureGuide) => {
172
172
  try {
173
- const compressed = await compressJpeg(photo.path, guide);
173
+ const compressed = await compressJpeg(photo.filePath, guide);
174
174
  if (compressed.byteLength > MAX_BYTES) {
175
175
  setBannerError(t.documents_ocr.fileTooLarge);
176
176
  // Stay on the capture phase so the user can retake immediately.
@@ -438,7 +438,7 @@ async function compressJpeg(
438
438
  //
439
439
  // We crop strictly to the on-screen guide rectangle the user centred the
440
440
  // document in; we never inspect pixels and we never rotate based on how the
441
- // phone was held — `DocumentCapture` pins `outputOrientation="preview"` so
441
+ // phone was held — `DocumentCapture` pins `orientationSource="interface"` so
442
442
  // the capture always comes back in the orientation the user framed.
443
443
  const loadContext = ImageManipulatorModule.manipulate(source);
444
444
  const loaded = await loadContext.renderAsync();