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

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 (76) hide show
  1. package/README.md +47 -17
  2. package/lib/commonjs/camera/DocumentCapture.js +57 -35
  3. package/lib/commonjs/camera/DocumentCapture.js.map +1 -1
  4. package/lib/commonjs/camera/LivenessCamera.js +240 -87
  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/i18n/strings/en.js +1 -0
  9. package/lib/commonjs/i18n/strings/en.js.map +1 -1
  10. package/lib/commonjs/i18n/strings/es.js +1 -0
  11. package/lib/commonjs/i18n/strings/es.js.map +1 -1
  12. package/lib/commonjs/steps/DocumentsOcrStep.js +140 -20
  13. package/lib/commonjs/steps/DocumentsOcrStep.js.map +1 -1
  14. package/lib/commonjs/steps/LivenessMatchStep.js +361 -63
  15. package/lib/commonjs/steps/LivenessMatchStep.js.map +1 -1
  16. package/lib/commonjs/transport/irisWebSocket.js +38 -3
  17. package/lib/commonjs/transport/irisWebSocket.js.map +1 -1
  18. package/lib/commonjs/ui/icons/StepIcon.js +8 -3
  19. package/lib/commonjs/ui/icons/StepIcon.js.map +1 -1
  20. package/lib/commonjs/ui/overlays/LoadingOverlay.js +1 -1
  21. package/lib/commonjs/ui/overlays/LoadingOverlay.js.map +1 -1
  22. package/lib/commonjs/ui/overlays/RetryDialog.js +1 -1
  23. package/lib/commonjs/ui/overlays/RetryDialog.js.map +1 -1
  24. package/lib/commonjs/utils/jpegFromUri.js +54 -14
  25. package/lib/commonjs/utils/jpegFromUri.js.map +1 -1
  26. package/lib/module/camera/DocumentCapture.js +58 -36
  27. package/lib/module/camera/DocumentCapture.js.map +1 -1
  28. package/lib/module/camera/LivenessCamera.js +242 -89
  29. package/lib/module/camera/LivenessCamera.js.map +1 -1
  30. package/lib/module/camera/MapAddressPicker.js +1 -1
  31. package/lib/module/camera/MapAddressPicker.js.map +1 -1
  32. package/lib/module/i18n/strings/en.js +1 -0
  33. package/lib/module/i18n/strings/en.js.map +1 -1
  34. package/lib/module/i18n/strings/es.js +1 -0
  35. package/lib/module/i18n/strings/es.js.map +1 -1
  36. package/lib/module/steps/DocumentsOcrStep.js +140 -20
  37. package/lib/module/steps/DocumentsOcrStep.js.map +1 -1
  38. package/lib/module/steps/LivenessMatchStep.js +364 -66
  39. package/lib/module/steps/LivenessMatchStep.js.map +1 -1
  40. package/lib/module/transport/irisWebSocket.js +38 -3
  41. package/lib/module/transport/irisWebSocket.js.map +1 -1
  42. package/lib/module/ui/icons/StepIcon.js +8 -3
  43. package/lib/module/ui/icons/StepIcon.js.map +1 -1
  44. package/lib/module/ui/overlays/LoadingOverlay.js +1 -1
  45. package/lib/module/ui/overlays/LoadingOverlay.js.map +1 -1
  46. package/lib/module/ui/overlays/RetryDialog.js +1 -1
  47. package/lib/module/ui/overlays/RetryDialog.js.map +1 -1
  48. package/lib/module/utils/jpegFromUri.js +52 -14
  49. package/lib/module/utils/jpegFromUri.js.map +1 -1
  50. package/lib/typescript/camera/DocumentCapture.d.ts +15 -3
  51. package/lib/typescript/camera/DocumentCapture.d.ts.map +1 -1
  52. package/lib/typescript/camera/LivenessCamera.d.ts +101 -10
  53. package/lib/typescript/camera/LivenessCamera.d.ts.map +1 -1
  54. package/lib/typescript/i18n/strings/en.d.ts.map +1 -1
  55. package/lib/typescript/i18n/strings/es.d.ts +1 -0
  56. package/lib/typescript/i18n/strings/es.d.ts.map +1 -1
  57. package/lib/typescript/steps/DocumentsOcrStep.d.ts.map +1 -1
  58. package/lib/typescript/steps/LivenessMatchStep.d.ts.map +1 -1
  59. package/lib/typescript/transport/irisWebSocket.d.ts.map +1 -1
  60. package/lib/typescript/ui/icons/StepIcon.d.ts +7 -2
  61. package/lib/typescript/ui/icons/StepIcon.d.ts.map +1 -1
  62. package/lib/typescript/utils/jpegFromUri.d.ts +31 -10
  63. package/lib/typescript/utils/jpegFromUri.d.ts.map +1 -1
  64. package/package.json +20 -14
  65. package/src/camera/DocumentCapture.tsx +59 -41
  66. package/src/camera/LivenessCamera.tsx +283 -89
  67. package/src/camera/MapAddressPicker.tsx +1 -1
  68. package/src/i18n/strings/en.ts +2 -0
  69. package/src/i18n/strings/es.ts +2 -0
  70. package/src/steps/DocumentsOcrStep.tsx +160 -18
  71. package/src/steps/LivenessMatchStep.tsx +416 -89
  72. package/src/transport/irisWebSocket.ts +32 -2
  73. package/src/ui/icons/StepIcon.tsx +9 -3
  74. package/src/ui/overlays/LoadingOverlay.tsx +1 -1
  75. package/src/ui/overlays/RetryDialog.tsx +1 -1
  76. package/src/utils/jpegFromUri.ts +54 -16
@@ -17,7 +17,7 @@
17
17
  */
18
18
 
19
19
  import { useCallback, useEffect, useRef, useState } from 'react';
20
- import { ScrollView, StyleSheet, Text, View } from 'react-native';
20
+ import { Image, ScrollView, StyleSheet, Text, View } from 'react-native';
21
21
  // `expo-file-system` v19's `File` class wraps a `file://` path with a Blob-
22
22
  // compatible API (`arrayBuffer`, `size`, `delete`). We read the recorded mp4
23
23
  // to bytes in JS and PUT them with the global `fetch`. For the typical
@@ -36,14 +36,30 @@ import { StepIcon } from '../ui/icons/StepIcon';
36
36
  import { mixHex, useTheme } from '../ui/theme';
37
37
  import { getStrings } from '../i18n';
38
38
  import { log } from '../utils/log';
39
- import { readJpegFromUri } from '../utils/jpegFromUri';
39
+ import { byteLengthOfUri, readBytesFromUri, readJpegFromUri } from '../utils/jpegFromUri';
40
+ import { bytesToBase64 } from '../utils/base64';
40
41
  import { buildSignedFrameEnvelope, importHmacKey } from '../utils/hmac';
41
42
  import { TERMINAL_WARNING_CODES, openIrisWebSocket } from '../transport/irisWebSocket';
42
- import { LivenessCamera } from '../camera/LivenessCamera';
43
+ import { LivenessCamera, ACTIVE_LIVENESS_CAMERA_VARIANT } from '../camera/LivenessCamera';
43
44
  import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
44
45
  // Capture loop defaults tuned for the Iris orchestrator's frame cadence.
45
46
  const FRAME_MS_DEFAULT = 350;
46
47
  const FRAME_MS_TURN = 220;
48
+ /**
49
+ * BLINK needs a frame to land while the eyes are closed, a ~150–300 ms window
50
+ * (OSDKR-24). The web SDK paces it at 150 ms; at the default 350 ms an Edge 30
51
+ * Neo sent 12 frames in the 8 s window and the blink never registered. The
52
+ * capture pipeline still caps the real rate — this only stops the timer from
53
+ * adding idle gaps on top of it.
54
+ */
55
+ const FRAME_MS_BLINK = 150;
56
+ /**
57
+ * No frame is sent during the first second after SESSION_READY (OSDKR-24).
58
+ * Iris gates positioning on the mean sharpness of the whole session, so the
59
+ * frames taken while the user is still settling into the oval weigh on every
60
+ * later decision. The 1–2 s before the first CHALLENGE absorbs the wait.
61
+ */
62
+ const CAPTURE_WARMUP_MS = 1000;
47
63
  const PROGRESS_WATCHDOG_MS = 25_000;
48
64
  /**
49
65
  * Hard ceiling for the POST /liveness-verify call that runs after
@@ -53,7 +69,154 @@ const PROGRESS_WATCHDOG_MS = 25_000;
53
69
  */
54
70
  const LIVENESS_VERIFY_TIMEOUT_MS = 20_000;
55
71
  const FRAME_MAX_LONG_EDGE = 720;
56
- const FRAME_QUALITY = 0.55;
72
+ // Match the web SDK's canvas JPEG (~0.92) closely enough that MiniFAS does
73
+ // not treat block artefacts as a screen replay. 0.55 (the previous value)
74
+ // was the other half of the spoof-false-positive we saw after the v5
75
+ // migration: ZSL fallback JPEGs re-compressed this hard scored `screen ≈ 0.95`.
76
+ const FRAME_QUALITY = 0.85;
77
+
78
+ /** A captured frame waiting for the processor, and how long the camera took on it. */
79
+
80
+ /** A frame scaled to the wire width and encoded as JPEG. */
81
+
82
+ /**
83
+ * Releases the camera buffer an in-memory frame holds. A frame that is
84
+ * dropped instead of encoded must go through here, or CameraX runs out of
85
+ * buffers and the next capture stalls.
86
+ */
87
+ function releaseFrame(frame) {
88
+ if (frame.kind !== 'memory') return;
89
+ try {
90
+ frame.photo.dispose();
91
+ } catch {
92
+ // Already released.
93
+ }
94
+ }
95
+
96
+ /**
97
+ * Scales a captured frame to the wire width and encodes it as JPEG. An
98
+ * in-memory frame's camera buffer is released as soon as its pixels are
99
+ * copied out, whether encoding then succeeds or not.
100
+ */
101
+ async function encodeFrame(frame) {
102
+ // Iris reads yaw off UN-mirrored frames (OSDKR-23): a mirrored frame turns
103
+ // TURN_LEFT into TURN_RIGHT. The file path already delivers them
104
+ // un-mirrored — do not flip it. The in-memory path must undo the mirroring
105
+ // `toImage()` applies to front-camera photos (see below).
106
+ if (frame.kind === 'file') {
107
+ const compressed = await ImageManipulator.manipulateAsync(frame.filePath.startsWith('file://') ? frame.filePath : `file://${frame.filePath}`, [{
108
+ resize: {
109
+ width: FRAME_MAX_LONG_EDGE
110
+ }
111
+ }], {
112
+ compress: FRAME_QUALITY,
113
+ format: ImageManipulator.SaveFormat.JPEG
114
+ });
115
+ const jpeg = await readJpegFromUri(compressed.uri);
116
+ return {
117
+ jpeg,
118
+ wireWidth: compressed.width,
119
+ wireHeight: compressed.height
120
+ };
121
+ }
122
+ const {
123
+ photo
124
+ } = frame;
125
+ const photoOrientation = photo.orientation;
126
+ const photoMirrored = photo.isMirrored;
127
+ let image;
128
+ try {
129
+ image = await photo.toImageAsync();
130
+ } finally {
131
+ releaseFrame(frame);
132
+ }
133
+ const captureSize = {
134
+ width: image.width,
135
+ height: image.height
136
+ };
137
+ const wireWidth = FRAME_MAX_LONG_EDGE;
138
+ const wireHeight = Math.round(image.height * wireWidth / image.width);
139
+ let wireImage;
140
+ try {
141
+ wireImage = await image.resizeAsync(wireWidth, wireHeight);
142
+ } finally {
143
+ image.dispose();
144
+ }
145
+ // `toImage()` mirrors front-camera photos (`isMirrored`), which the file
146
+ // path never did. Left as is, an Edge 30 Neo user turning left moved the yaw
147
+ // by -36° and Iris scored TURN_LEFT at 0 for the whole window. Undo it on
148
+ // the small image, where it is cheap.
149
+ if (photoMirrored) {
150
+ const mirrored = wireImage;
151
+ try {
152
+ wireImage = await mirrored.mirrorHorizontallyAsync();
153
+ } finally {
154
+ mirrored.dispose();
155
+ }
156
+ }
157
+ let encoded;
158
+ try {
159
+ // Same encoder as the file path (`Bitmap.compress`), on its 0–100 scale.
160
+ encoded = await wireImage.toEncodedImageDataAsync('jpg', Math.round(FRAME_QUALITY * 100));
161
+ } finally {
162
+ wireImage.dispose();
163
+ }
164
+ // Copy out of the native-backed buffer before the image objects go away.
165
+ const bytes = new Uint8Array(encoded.buffer.slice(0));
166
+ return {
167
+ jpeg: {
168
+ bytes,
169
+ base64: bytesToBase64(bytes),
170
+ byteLength: bytes.byteLength
171
+ },
172
+ wireWidth,
173
+ wireHeight,
174
+ captureSize,
175
+ photoOrientation,
176
+ photoMirrored
177
+ };
178
+ }
179
+
180
+ /**
181
+ * DIAGNOSTIC (OSDKR-24): logs the capture size CameraX negotiated next to the
182
+ * frame that went to Iris, and how long the camera and the processing took
183
+ * on it. Fire-and-forget — a failure here must never cost a frame.
184
+ */
185
+ async function logCaptureDiagnostics(sample) {
186
+ try {
187
+ const {
188
+ encoded
189
+ } = sample;
190
+ let captureSize = encoded.captureSize;
191
+ let captureBytes = null;
192
+ if (!captureSize && sample.capturePath) {
193
+ const captureUri = sample.capturePath.startsWith('file://') ? sample.capturePath : `file://${sample.capturePath}`;
194
+ captureSize = await Image.getSize(captureUri);
195
+ captureBytes = byteLengthOfUri(captureUri);
196
+ }
197
+ if (!captureSize) return;
198
+ log.warn('[Liveness][diag] capture', {
199
+ variant: ACTIVE_LIVENESS_CAMERA_VARIANT,
200
+ source: sample.source,
201
+ captureWidth: captureSize.width,
202
+ captureHeight: captureSize.height,
203
+ captureBytes,
204
+ wireWidth: encoded.wireWidth,
205
+ wireHeight: encoded.wireHeight,
206
+ wireBytes: encoded.jpeg.byteLength,
207
+ // Short edge of the capture over the wire width. Below 1 the resize
208
+ // UPSCALED the capture.
209
+ captureToWire: Number((Math.min(captureSize.width, captureSize.height) / FRAME_MAX_LONG_EDGE).toFixed(2)),
210
+ captureMs: sample.captureMs,
211
+ processMs: sample.processMs,
212
+ photoOrientation: encoded.photoOrientation,
213
+ photoMirrored: encoded.photoMirrored,
214
+ challenge: sample.challenge
215
+ });
216
+ } catch (err) {
217
+ log.warn('[Liveness][diag] capture size unavailable', err);
218
+ }
219
+ }
57
220
  /**
58
221
  * Hard ceiling for the video upload PUT to GCS that runs between SESSION_COMPLETE
59
222
  * and POST /liveness-verify. Long enough for a 5 MB upload on a slow mobile link
@@ -151,10 +314,31 @@ function LivenessMatchView({
151
314
  const lastChallengeMetaRef = useRef(null);
152
315
  const frameMsRef = useRef(FRAME_MS_DEFAULT);
153
316
  const captureTimerRef = useRef(null);
154
- const inFlightRef = useRef(false);
317
+ // Capture and processing run as a two-stage pipeline (OSDKR-24): the camera
318
+ // takes frame N+1 while frame N is resized, signed and sent. On an Edge 30
319
+ // Neo the camera takes ~320 ms of a ~730 ms cycle and our processing the
320
+ // rest; running them back to back capped the loop at ~1.35 fps, against the
321
+ // 2.8–4.5 fps the challenges are paced for.
322
+ const captureInFlightRef = useRef(false);
323
+ const processingRef = useRef(false);
324
+ // At most one captured frame waits for the processor, and no new capture
325
+ // starts while one waits, so frames never queue up and go stale. An
326
+ // in-memory frame holds a camera buffer while it waits: dropping one must
327
+ // release it.
328
+ const pendingFrameRef = useRef(null);
329
+ // Bumped by `stopCapture` so a capture or a processing pass still running
330
+ // when the loop stops is dropped instead of sent.
331
+ const captureGenerationRef = useRef(0);
332
+ // No capture starts before this timestamp. See CAPTURE_WARMUP_MS.
333
+ const captureNotBeforeRef = useRef(0);
155
334
  const framesSentRef = useRef(0);
156
335
  const watchdogRef = useRef(null);
157
336
  const finalizingRef = useRef(false);
337
+ // Set when we are about to show the in-flow retry dialog. Iris often
338
+ // closes with 1000 in the same tick as the terminal WARNING, and that close
339
+ // can beat our own 4001 — without this flag the generic onClose would
340
+ // treat a handled rejection as "socket closed before the step finalized".
341
+ const closingForRetryRef = useRef(false);
158
342
  const toastTimerRef = useRef(null);
159
343
  // Tracks the toast currently on screen so we can extend its visibility when
160
344
  // the same message arrives again (instead of dismount/remount, which made
@@ -232,13 +416,23 @@ function LivenessMatchView({
232
416
  watchdogRef.current = null;
233
417
  }
234
418
  }, []);
235
- const stopCapture = useCallback(() => {
419
+ const clearCaptureTimer = useCallback(() => {
236
420
  if (captureTimerRef.current) {
237
421
  clearInterval(captureTimerRef.current);
238
422
  captureTimerRef.current = null;
239
423
  }
240
- inFlightRef.current = false;
241
424
  }, []);
425
+ const stopCapture = useCallback(() => {
426
+ clearCaptureTimer();
427
+ captureGenerationRef.current += 1;
428
+ const pending = pendingFrameRef.current;
429
+ pendingFrameRef.current = null;
430
+ if (pending) releaseFrame(pending.frame);
431
+ // Also recovers from a camera or processing call that never settled: the
432
+ // next loop start must not stay blocked on it.
433
+ captureInFlightRef.current = false;
434
+ processingRef.current = false;
435
+ }, [clearCaptureTimer]);
242
436
 
243
437
  // ── Video upload pipeline (OSDKR-4) ─────────────────────────────────────
244
438
  // Everything below is best-effort: never throws into the caller; never
@@ -282,32 +476,44 @@ function LivenessMatchView({
282
476
  });
283
477
  const t0 = Date.now();
284
478
  try {
285
- // Build a NATIVE React Native Blob from the `file://` URI: fetching
286
- // the local path returns a Response whose `.blob()` is the BlobModule
287
- // implementation that the bridge actually knows how to upload. Using
288
- // the expo-file-system `File` directly silently sends an empty body
289
- // (GCS responds 200 with a 0-byte object — exactly what we hit
290
- // before). Reading the bytes through the native Blob keeps the data
291
- // on the native side and uploads streamed from disk.
292
- const fileUri = video.path.startsWith('file://') ? video.path : `file://${video.path}`;
293
- const nativeBlob = await (await fetch(fileUri)).blob();
479
+ // Read the bytes with `expo-file-system`, NOT with `fetch(fileUri)`.
480
+ //
481
+ // This reverses what this code used to do, so it is worth spelling
482
+ // out. Under React Native's `fetch` the native Blob was the reliable
483
+ // body and passing bytes sent an empty one. Since Expo SDK 57 the
484
+ // global `fetch` is Expo's native HTTP client
485
+ // (`expo/src/winter/runtime.native.ts` → `install('fetch', ...)`),
486
+ // which does not handle the `file://` scheme: it answers with an empty
487
+ // body instead of failing, so reading the recording through it
488
+ // uploaded a 0-byte object while every status code reported success
489
+ // (OSDKR-22). Expo's `fetch` does accept any `ArrayBuffer.isView` as a
490
+ // request body, so the bytes go up directly.
491
+ const videoBytes = await readBytesFromUri(video.path);
294
492
  log.info('[Liveness] video upload body prepared', {
295
- blobSize: nativeBlob.size,
296
- blobType: nativeBlob.type
493
+ bytes: videoBytes.byteLength
297
494
  });
495
+ if (videoBytes.byteLength === 0) {
496
+ throw new Error('Recorded video read back as 0 bytes.');
497
+ }
298
498
  const result = await fetch(target.upload_url, {
299
499
  method: 'PUT',
300
500
  headers: {
301
501
  'Content-Type': VIDEO_CONTENT_TYPE
302
502
  },
303
- body: nativeBlob
503
+ body: videoBytes
304
504
  });
305
505
  const elapsedMs = Date.now() - t0;
306
506
  if (result.ok) {
507
+ // `sentBytes` is what we actually put on the wire; `sizeBytes` is
508
+ // the file size stat'd before reading. They must match — a mismatch,
509
+ // or an etag that repeats across sessions, means the body never
510
+ // reached the bucket (OSDKR-22).
307
511
  log.info('[Liveness] video upload ok', {
308
512
  status: result.status,
309
- elapsedMs,
310
- sizeBytes
513
+ sentBytes: videoBytes.byteLength,
514
+ sizeBytes,
515
+ etag: result.headers.get('etag'),
516
+ elapsedMs
311
517
  });
312
518
  videoOutcomeRef.current = 'uploaded';
313
519
  videoMetaRef.current = {
@@ -355,7 +561,17 @@ function LivenessMatchView({
355
561
  videoTempPathRef.current = null;
356
562
  }
357
563
  }, [deleteVideoTemp]);
358
- const startVideoRecordingIfEnabled = useCallback(() => {
564
+ const startVideoRecordingIfEnabled = useCallback(async () => {
565
+ // Idempotent on purpose: with the recorder now starting at
566
+ // POSITIONING_READY, the first CHALLENGE calls this again, and both paths
567
+ // are legitimate — positioning can also be skipped entirely.
568
+ //
569
+ // Without this guard the second call would replace the two Deferreds below
570
+ // while the first recording is still running. `LivenessCamera` returns
571
+ // early because it already holds a Recorder, so the fresh promises would
572
+ // never settle and the finalize path would await them forever — the
573
+ // "analyzing" hang from OSDKR-23, reintroduced through a different door.
574
+ if (videoOutcomeRef.current === 'recording') return;
359
575
  if (!videoUploadRef.current) {
360
576
  log.info('[Liveness] video skipped: no video_upload in liveness-init');
361
577
  return;
@@ -395,7 +611,7 @@ function LivenessMatchView({
395
611
  };
396
612
  });
397
613
  try {
398
- camera.startVideoRecording({
614
+ await camera.startVideoRecording({
399
615
  onRecordingFinished: video => {
400
616
  log.info('[Liveness] video recording finished', {
401
617
  path: video.path,
@@ -508,32 +724,36 @@ function LivenessMatchView({
508
724
  finish();
509
725
  })();
510
726
  }, [deleteVideoTemp, onCancel, stopCapture, stopVideoRecordingIfActive, stopWatchdog]);
511
- const captureAndSend = useCallback(async () => {
512
- if (inFlightRef.current) return;
513
- const ws = wsRef.current;
514
- if (!ws || !ws.isOpen()) return;
515
- inFlightRef.current = true;
727
+ const processAndSendFrame = useCallback(async (queued, generation) => {
728
+ processingRef.current = true;
729
+ const processStart = Date.now();
516
730
  try {
517
- const photo = await cameraRef.current?.takeFrame();
518
- if (!photo || !ws.isOpen()) return;
519
- // Front-camera frames come back mirrored (vision-camera's default for
520
- // front cam, which we keep so the recorded mp4 has a correct rotation
521
- // matrix — see the `isMirrored` comment in LivenessCamera). For Iris,
522
- // we want the un-mirrored yaw so TURN_LEFT/RIGHT challenges map to
523
- // real-world directions, so we flip the JPEG horizontally here before
524
- // signing and sending.
525
- const compressed = await ImageManipulator.manipulateAsync(photo.path.startsWith('file://') ? photo.path : `file://${photo.path}`, [{
526
- resize: {
527
- width: FRAME_MAX_LONG_EDGE
528
- }
529
- }, {
530
- flip: ImageManipulator.FlipType.Horizontal
531
- }], {
532
- compress: FRAME_QUALITY,
533
- format: ImageManipulator.SaveFormat.JPEG
534
- });
535
- if (!ws.isOpen()) return;
536
- const jpeg = await readJpegFromUri(compressed.uri);
731
+ const ws = wsRef.current;
732
+ if (!ws || !ws.isOpen()) {
733
+ releaseFrame(queued.frame);
734
+ return;
735
+ }
736
+ const encoded = await encodeFrame(queued.frame);
737
+ const {
738
+ jpeg
739
+ } = encoded;
740
+ // The loop stopped (or the socket closed) while this frame was being
741
+ // processed: drop it rather than send a frame from before the stop.
742
+ if (generation !== captureGenerationRef.current || !ws.isOpen()) return;
743
+ // DIAGNOSTIC (OSDKR-24): one line every 10th frame comparing what the
744
+ // camera captured with what went on the wire, plus how long each
745
+ // pipeline stage took. `warn` on purpose: `info` is silent in the
746
+ // release builds testers run.
747
+ if (framesSentRef.current % 10 === 0) {
748
+ void logCaptureDiagnostics({
749
+ encoded,
750
+ source: queued.frame.kind,
751
+ capturePath: queued.frame.kind === 'file' ? queued.frame.filePath : undefined,
752
+ captureMs: queued.captureMs,
753
+ processMs: Date.now() - processStart,
754
+ challenge: currentChallengeRef.current ?? null
755
+ });
756
+ }
537
757
  const key = hmacRef.current;
538
758
  if (key) {
539
759
  const envelope = buildSignedFrameEnvelope({
@@ -555,16 +775,60 @@ function LivenessMatchView({
555
775
  } catch (err) {
556
776
  log.warn('[Liveness] frame send failed', err);
557
777
  } finally {
558
- inFlightRef.current = false;
778
+ // After a stop, `stopCapture` already reset the pipeline; a stale pass
779
+ // must not touch the state of the one that replaced it.
780
+ if (generation === captureGenerationRef.current) {
781
+ processingRef.current = false;
782
+ const next = pendingFrameRef.current;
783
+ if (next) {
784
+ pendingFrameRef.current = null;
785
+ void processAndSendFrame(next, generation);
786
+ }
787
+ }
559
788
  }
560
789
  }, [sessionId]);
790
+ const captureTick = useCallback(async () => {
791
+ if (captureInFlightRef.current || pendingFrameRef.current) return;
792
+ if (Date.now() < captureNotBeforeRef.current) return;
793
+ const ws = wsRef.current;
794
+ if (!ws || !ws.isOpen()) return;
795
+ const generation = captureGenerationRef.current;
796
+ captureInFlightRef.current = true;
797
+ const captureStart = Date.now();
798
+ let frame;
799
+ try {
800
+ frame = await cameraRef.current?.takeFrame();
801
+ } catch (err) {
802
+ log.warn('[Liveness] frame capture failed', err);
803
+ } finally {
804
+ if (generation === captureGenerationRef.current) {
805
+ captureInFlightRef.current = false;
806
+ }
807
+ }
808
+ if (!frame) return;
809
+ if (generation !== captureGenerationRef.current) {
810
+ releaseFrame(frame);
811
+ return;
812
+ }
813
+ const queued = {
814
+ frame,
815
+ captureMs: Date.now() - captureStart
816
+ };
817
+ if (processingRef.current) {
818
+ pendingFrameRef.current = queued;
819
+ } else {
820
+ void processAndSendFrame(queued, generation);
821
+ }
822
+ }, [processAndSendFrame]);
561
823
  const startCaptureLoop = useCallback(ms => {
562
- stopCapture();
824
+ // Only the pacing changes here: frames already in the pipeline keep
825
+ // going, so a challenge switching the fps does not cost a frame.
826
+ clearCaptureTimer();
563
827
  frameMsRef.current = ms;
564
828
  captureTimerRef.current = setInterval(() => {
565
- void captureAndSend();
829
+ void captureTick();
566
830
  }, ms);
567
- }, [captureAndSend, stopCapture]);
831
+ }, [captureTick, clearCaptureTimer]);
568
832
  const adjustFps = useCallback(ms => {
569
833
  if (frameMsRef.current === ms) return;
570
834
  if (captureTimerRef.current) {
@@ -578,6 +842,7 @@ function LivenessMatchView({
578
842
  return t.liveness.challenge[id] ?? '';
579
843
  }, [t.liveness.challenge]);
580
844
  const presentTerminalRetry = useCallback((code, message) => {
845
+ closingForRetryRef.current = true;
581
846
  stopCapture();
582
847
  stopWatchdog();
583
848
  try {
@@ -625,11 +890,13 @@ function LivenessMatchView({
625
890
  // failed before the user understood what was being asked.
626
891
  setChallengeText(t.liveness.centerFace);
627
892
  showToast('success', t.liveness.getReady);
893
+ captureNotBeforeRef.current = Date.now() + CAPTURE_WARMUP_MS;
628
894
  startCaptureLoop(FRAME_MS_DEFAULT);
629
- // Start the local mp4 recording in parallel with the frame loop, if
630
- // the backend opted in via `video_upload` in /liveness-init. Pure
631
- // best-effort: any failure here is logged and never blocks liveness.
632
- startVideoRecordingIfEnabled();
895
+ // Do not start the evidence recorder yet. MiniFAS and positioning
896
+ // run on these first seconds; a photo+video session on Android
897
+ // produced blurry stills (`LOW_SHARPNESS`) and a screen-replay
898
+ // score. Recording starts on POSITIONING_READY (or the first
899
+ // CHALLENGE if positioning is disabled).
633
900
  resetWatchdog();
634
901
  return;
635
902
  }
@@ -646,7 +913,7 @@ function LivenessMatchView({
646
913
  total: msg.totalChallenges
647
914
  };
648
915
  }
649
- adjustFps(ch === 'TURN_LEFT' || ch === 'TURN_RIGHT' ? FRAME_MS_TURN : FRAME_MS_DEFAULT);
916
+ adjustFps(ch === 'TURN_LEFT' || ch === 'TURN_RIGHT' ? FRAME_MS_TURN : ch === 'BLINK' ? FRAME_MS_BLINK : FRAME_MS_DEFAULT);
650
917
  setChallengeText(challengeLabel(ch));
651
918
  // Map distance challenges to an oval-size cue so the viewfinder
652
919
  // shape reinforces the instruction (grows for closer, returns to
@@ -654,6 +921,9 @@ function LivenessMatchView({
654
921
  // oval — the dim mask shouldn't move under a turn / smile / blink.
655
922
  setOvalCue(ch === 'MOVE_CLOSER' ? 'MOVE_CLOSER' : ch === 'MOVE_FARTHER' ? 'MOVE_FARTHER' : 'NEUTRAL');
656
923
  setProgress(0);
924
+ // Positioning skipped or already passed — start the evidence
925
+ // recorder if it is not running yet (idempotent).
926
+ void startVideoRecordingIfEnabled();
657
927
  resetWatchdog();
658
928
  return;
659
929
  }
@@ -714,11 +984,20 @@ function LivenessMatchView({
714
984
  // bar, neutral oval, persistent hint — and let the SAME challenge
715
985
  // re-arrive on its own once the user is well positioned again.
716
986
  if (msg.code === 'CHALLENGE_REPOSITION') {
987
+ const abortedChallenge = currentChallengeRef.current;
717
988
  currentChallengeRef.current = null;
718
989
  adjustFps(FRAME_MS_DEFAULT);
719
990
  setProgress(null);
720
991
  setOvalCue('NEUTRAL');
721
- const repositionText = msg.message ?? t.liveness.repositioning;
992
+ // A MOVE_FARTHER abort is the one case where the orchestrator's
993
+ // generic "center your face and improve the lighting" sends the
994
+ // user the wrong way (OSDKR-24). Moving away shrinks the face, and
995
+ // with it the sharpness Iris measures, until the mid-challenge
996
+ // check aborts; the user then has to come back closer before
997
+ // positioning reopens. On an Edge 30 Neo they stayed at the far
998
+ // distance for 43 s. Our own copy overrides the server text here
999
+ // until IRIS-31 stops that abort at the source.
1000
+ const repositionText = abortedChallenge === 'MOVE_FARTHER' ? t.liveness.repositioningAfterMoveFarther : msg.message ?? t.liveness.repositioning;
722
1001
  setChallengeText(repositionText);
723
1002
  showToast('warning', repositionText);
724
1003
  resetWatchdog();
@@ -774,6 +1053,9 @@ function LivenessMatchView({
774
1053
  const baseText = msg.message ?? codedFallback;
775
1054
  const text = isPositioningReady ? t.liveness.positioningReady : typeof msg.consecutiveMisses === 'number' && msg.consecutiveMisses >= 3 ? t.liveness.warningConsecutiveMisses.replace('{n}', String(msg.consecutiveMisses)).concat(' — ', baseText) : baseText;
776
1055
  showToast(isPositioningReady ? 'success' : 'warning', text);
1056
+ if (isPositioningReady) {
1057
+ void startVideoRecordingIfEnabled();
1058
+ }
777
1059
  resetWatchdog();
778
1060
  return;
779
1061
  }
@@ -873,6 +1155,7 @@ function LivenessMatchView({
873
1155
  setRetry(null);
874
1156
  setStatusText(t.liveness.connecting);
875
1157
  finalizingRef.current = false;
1158
+ closingForRetryRef.current = false;
876
1159
  framesSentRef.current = 0;
877
1160
  currentChallengeRef.current = null;
878
1161
  lastChallengeMetaRef.current = null;
@@ -950,15 +1233,30 @@ function LivenessMatchView({
950
1233
  // — this handler is registered via closure on a stale render,
951
1234
  // so `retry` reads `null` even when we just called `setRetry`.
952
1235
  // The close code is reliable: we always pair 4001 with the
953
- // retry-dialog mount.
954
- if (code === 4001) return;
1236
+ // retry-dialog mount. `closingForRetryRef` covers the race where
1237
+ // Iris's own 1000 arrives first (it always closes NORMAL after a
1238
+ // terminal WARNING).
1239
+ if (code === 4001 || closingForRetryRef.current) return;
955
1240
  stopCapture();
956
- stopWatchdog();
957
- if (code === 1000) return;
958
- failWith({
959
- code: SdkErrorCode.LIVENESS_FAILED,
960
- message: `Iris WebSocket closed before completion (code=${code}${reason ? `, reason=${reason}` : ''}).`
1241
+
1242
+ // Reaching here means the socket closed and the step never
1243
+ // finalized, so we do not know how the session ended (OSDKR-23).
1244
+ //
1245
+ // A close code cannot tell us: Iris closes with 1000 after a
1246
+ // successful SESSION_COMPLETE, after CHALLENGE_NOT_CONFIRMED, and
1247
+ // after SPOOF_RISK_HIGH alike. It always sends the deciding message
1248
+ // immediately before closing, so a 1000 here means we lost it.
1249
+ //
1250
+ // This used to `stopWatchdog()` and then return on 1000, which left
1251
+ // the step on the "analyzing" overlay forever with every safety net
1252
+ // disarmed. Route the user into the same recovery a terminal warning
1253
+ // uses instead: the session did not complete as far as we can tell,
1254
+ // and offering a retry is both honest and actionable.
1255
+ log.warn('[Liveness] socket closed before the step finalized', {
1256
+ code,
1257
+ reason
961
1258
  });
1259
+ presentTerminalRetry('CONNECTION_CLOSED', t.liveness.terminalRetryFallback);
962
1260
  }
963
1261
  });
964
1262
  } catch (err) {
@@ -970,7 +1268,7 @@ function LivenessMatchView({
970
1268
  return;
971
1269
  }
972
1270
  wsRef.current = connection;
973
- }, [api, calibrationLabel, failWith, handleWsMessage, locale, retry, sessionId, stopCapture, stopWatchdog, t.liveness.connecting, t.liveness.preparingCamera]);
1271
+ }, [api, calibrationLabel, failWith, handleWsMessage, locale, presentTerminalRetry, retry, sessionId, stopCapture, t.liveness.connecting, t.liveness.preparingCamera, t.liveness.terminalRetryFallback]);
974
1272
 
975
1273
  // Re-run after a terminal retry — same cleanup as start, but reuses the
976
1274
  // mounted camera (no DOM teardown).