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

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 (33) hide show
  1. package/lib/commonjs/camera/LivenessCamera.js +151 -39
  2. package/lib/commonjs/camera/LivenessCamera.js.map +1 -1
  3. package/lib/commonjs/i18n/strings/en.js +1 -0
  4. package/lib/commonjs/i18n/strings/en.js.map +1 -1
  5. package/lib/commonjs/i18n/strings/es.js +1 -0
  6. package/lib/commonjs/i18n/strings/es.js.map +1 -1
  7. package/lib/commonjs/steps/LivenessMatchStep.js +333 -50
  8. package/lib/commonjs/steps/LivenessMatchStep.js.map +1 -1
  9. package/lib/commonjs/transport/irisWebSocket.js +38 -3
  10. package/lib/commonjs/transport/irisWebSocket.js.map +1 -1
  11. package/lib/module/camera/LivenessCamera.js +152 -40
  12. package/lib/module/camera/LivenessCamera.js.map +1 -1
  13. package/lib/module/i18n/strings/en.js +1 -0
  14. package/lib/module/i18n/strings/en.js.map +1 -1
  15. package/lib/module/i18n/strings/es.js +1 -0
  16. package/lib/module/i18n/strings/es.js.map +1 -1
  17. package/lib/module/steps/LivenessMatchStep.js +336 -53
  18. package/lib/module/steps/LivenessMatchStep.js.map +1 -1
  19. package/lib/module/transport/irisWebSocket.js +38 -3
  20. package/lib/module/transport/irisWebSocket.js.map +1 -1
  21. package/lib/typescript/camera/LivenessCamera.d.ts +78 -10
  22. package/lib/typescript/camera/LivenessCamera.d.ts.map +1 -1
  23. package/lib/typescript/i18n/strings/en.d.ts.map +1 -1
  24. package/lib/typescript/i18n/strings/es.d.ts +1 -0
  25. package/lib/typescript/i18n/strings/es.d.ts.map +1 -1
  26. package/lib/typescript/steps/LivenessMatchStep.d.ts.map +1 -1
  27. package/lib/typescript/transport/irisWebSocket.d.ts.map +1 -1
  28. package/package.json +1 -1
  29. package/src/camera/LivenessCamera.tsx +172 -38
  30. package/src/i18n/strings/en.ts +2 -0
  31. package/src/i18n/strings/es.ts +2 -0
  32. package/src/steps/LivenessMatchStep.tsx +382 -75
  33. package/src/transport/irisWebSocket.ts +32 -2
@@ -19,6 +19,7 @@ var _theme = require("../ui/theme");
19
19
  var _i18n = require("../i18n");
20
20
  var _log = require("../utils/log");
21
21
  var _jpegFromUri = require("../utils/jpegFromUri");
22
+ var _base = require("../utils/base64");
22
23
  var _hmac = require("../utils/hmac");
23
24
  var _irisWebSocket = require("../transport/irisWebSocket");
24
25
  var _LivenessCamera = require("../camera/LivenessCamera");
@@ -50,6 +51,21 @@ function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r
50
51
  // Capture loop defaults tuned for the Iris orchestrator's frame cadence.
51
52
  const FRAME_MS_DEFAULT = 350;
52
53
  const FRAME_MS_TURN = 220;
54
+ /**
55
+ * BLINK needs a frame to land while the eyes are closed, a ~150–300 ms window
56
+ * (OSDKR-24). The web SDK paces it at 150 ms; at the default 350 ms an Edge 30
57
+ * Neo sent 12 frames in the 8 s window and the blink never registered. The
58
+ * capture pipeline still caps the real rate — this only stops the timer from
59
+ * adding idle gaps on top of it.
60
+ */
61
+ const FRAME_MS_BLINK = 150;
62
+ /**
63
+ * No frame is sent during the first second after SESSION_READY (OSDKR-24).
64
+ * Iris gates positioning on the mean sharpness of the whole session, so the
65
+ * frames taken while the user is still settling into the oval weigh on every
66
+ * later decision. The 1–2 s before the first CHALLENGE absorbs the wait.
67
+ */
68
+ const CAPTURE_WARMUP_MS = 1000;
53
69
  const PROGRESS_WATCHDOG_MS = 25_000;
54
70
  /**
55
71
  * Hard ceiling for the POST /liveness-verify call that runs after
@@ -59,7 +75,154 @@ const PROGRESS_WATCHDOG_MS = 25_000;
59
75
  */
60
76
  const LIVENESS_VERIFY_TIMEOUT_MS = 20_000;
61
77
  const FRAME_MAX_LONG_EDGE = 720;
62
- const FRAME_QUALITY = 0.55;
78
+ // Match the web SDK's canvas JPEG (~0.92) closely enough that MiniFAS does
79
+ // not treat block artefacts as a screen replay. 0.55 (the previous value)
80
+ // was the other half of the spoof-false-positive we saw after the v5
81
+ // migration: ZSL fallback JPEGs re-compressed this hard scored `screen ≈ 0.95`.
82
+ const FRAME_QUALITY = 0.85;
83
+
84
+ /** A captured frame waiting for the processor, and how long the camera took on it. */
85
+
86
+ /** A frame scaled to the wire width and encoded as JPEG. */
87
+
88
+ /**
89
+ * Releases the camera buffer an in-memory frame holds. A frame that is
90
+ * dropped instead of encoded must go through here, or CameraX runs out of
91
+ * buffers and the next capture stalls.
92
+ */
93
+ function releaseFrame(frame) {
94
+ if (frame.kind !== 'memory') return;
95
+ try {
96
+ frame.photo.dispose();
97
+ } catch {
98
+ // Already released.
99
+ }
100
+ }
101
+
102
+ /**
103
+ * Scales a captured frame to the wire width and encodes it as JPEG. An
104
+ * in-memory frame's camera buffer is released as soon as its pixels are
105
+ * copied out, whether encoding then succeeds or not.
106
+ */
107
+ async function encodeFrame(frame) {
108
+ // Iris reads yaw off UN-mirrored frames (OSDKR-23): a mirrored frame turns
109
+ // TURN_LEFT into TURN_RIGHT. The file path already delivers them
110
+ // un-mirrored — do not flip it. The in-memory path must undo the mirroring
111
+ // `toImage()` applies to front-camera photos (see below).
112
+ if (frame.kind === 'file') {
113
+ const compressed = await ImageManipulator.manipulateAsync(frame.filePath.startsWith('file://') ? frame.filePath : `file://${frame.filePath}`, [{
114
+ resize: {
115
+ width: FRAME_MAX_LONG_EDGE
116
+ }
117
+ }], {
118
+ compress: FRAME_QUALITY,
119
+ format: ImageManipulator.SaveFormat.JPEG
120
+ });
121
+ const jpeg = await (0, _jpegFromUri.readJpegFromUri)(compressed.uri);
122
+ return {
123
+ jpeg,
124
+ wireWidth: compressed.width,
125
+ wireHeight: compressed.height
126
+ };
127
+ }
128
+ const {
129
+ photo
130
+ } = frame;
131
+ const photoOrientation = photo.orientation;
132
+ const photoMirrored = photo.isMirrored;
133
+ let image;
134
+ try {
135
+ image = await photo.toImageAsync();
136
+ } finally {
137
+ releaseFrame(frame);
138
+ }
139
+ const captureSize = {
140
+ width: image.width,
141
+ height: image.height
142
+ };
143
+ const wireWidth = FRAME_MAX_LONG_EDGE;
144
+ const wireHeight = Math.round(image.height * wireWidth / image.width);
145
+ let wireImage;
146
+ try {
147
+ wireImage = await image.resizeAsync(wireWidth, wireHeight);
148
+ } finally {
149
+ image.dispose();
150
+ }
151
+ // `toImage()` mirrors front-camera photos (`isMirrored`), which the file
152
+ // path never did. Left as is, an Edge 30 Neo user turning left moved the yaw
153
+ // by -36° and Iris scored TURN_LEFT at 0 for the whole window. Undo it on
154
+ // the small image, where it is cheap.
155
+ if (photoMirrored) {
156
+ const mirrored = wireImage;
157
+ try {
158
+ wireImage = await mirrored.mirrorHorizontallyAsync();
159
+ } finally {
160
+ mirrored.dispose();
161
+ }
162
+ }
163
+ let encoded;
164
+ try {
165
+ // Same encoder as the file path (`Bitmap.compress`), on its 0–100 scale.
166
+ encoded = await wireImage.toEncodedImageDataAsync('jpg', Math.round(FRAME_QUALITY * 100));
167
+ } finally {
168
+ wireImage.dispose();
169
+ }
170
+ // Copy out of the native-backed buffer before the image objects go away.
171
+ const bytes = new Uint8Array(encoded.buffer.slice(0));
172
+ return {
173
+ jpeg: {
174
+ bytes,
175
+ base64: (0, _base.bytesToBase64)(bytes),
176
+ byteLength: bytes.byteLength
177
+ },
178
+ wireWidth,
179
+ wireHeight,
180
+ captureSize,
181
+ photoOrientation,
182
+ photoMirrored
183
+ };
184
+ }
185
+
186
+ /**
187
+ * DIAGNOSTIC (OSDKR-24): logs the capture size CameraX negotiated next to the
188
+ * frame that went to Iris, and how long the camera and the processing took
189
+ * on it. Fire-and-forget — a failure here must never cost a frame.
190
+ */
191
+ async function logCaptureDiagnostics(sample) {
192
+ try {
193
+ const {
194
+ encoded
195
+ } = sample;
196
+ let captureSize = encoded.captureSize;
197
+ let captureBytes = null;
198
+ if (!captureSize && sample.capturePath) {
199
+ const captureUri = sample.capturePath.startsWith('file://') ? sample.capturePath : `file://${sample.capturePath}`;
200
+ captureSize = await _reactNative.Image.getSize(captureUri);
201
+ captureBytes = (0, _jpegFromUri.byteLengthOfUri)(captureUri);
202
+ }
203
+ if (!captureSize) return;
204
+ _log.log.warn('[Liveness][diag] capture', {
205
+ variant: _LivenessCamera.ACTIVE_LIVENESS_CAMERA_VARIANT,
206
+ source: sample.source,
207
+ captureWidth: captureSize.width,
208
+ captureHeight: captureSize.height,
209
+ captureBytes,
210
+ wireWidth: encoded.wireWidth,
211
+ wireHeight: encoded.wireHeight,
212
+ wireBytes: encoded.jpeg.byteLength,
213
+ // Short edge of the capture over the wire width. Below 1 the resize
214
+ // UPSCALED the capture.
215
+ captureToWire: Number((Math.min(captureSize.width, captureSize.height) / FRAME_MAX_LONG_EDGE).toFixed(2)),
216
+ captureMs: sample.captureMs,
217
+ processMs: sample.processMs,
218
+ photoOrientation: encoded.photoOrientation,
219
+ photoMirrored: encoded.photoMirrored,
220
+ challenge: sample.challenge
221
+ });
222
+ } catch (err) {
223
+ _log.log.warn('[Liveness][diag] capture size unavailable', err);
224
+ }
225
+ }
63
226
  /**
64
227
  * Hard ceiling for the video upload PUT to GCS that runs between SESSION_COMPLETE
65
228
  * and POST /liveness-verify. Long enough for a 5 MB upload on a slow mobile link
@@ -158,10 +321,31 @@ function LivenessMatchView({
158
321
  const lastChallengeMetaRef = (0, _react.useRef)(null);
159
322
  const frameMsRef = (0, _react.useRef)(FRAME_MS_DEFAULT);
160
323
  const captureTimerRef = (0, _react.useRef)(null);
161
- const inFlightRef = (0, _react.useRef)(false);
324
+ // Capture and processing run as a two-stage pipeline (OSDKR-24): the camera
325
+ // takes frame N+1 while frame N is resized, signed and sent. On an Edge 30
326
+ // Neo the camera takes ~320 ms of a ~730 ms cycle and our processing the
327
+ // rest; running them back to back capped the loop at ~1.35 fps, against the
328
+ // 2.8–4.5 fps the challenges are paced for.
329
+ const captureInFlightRef = (0, _react.useRef)(false);
330
+ const processingRef = (0, _react.useRef)(false);
331
+ // At most one captured frame waits for the processor, and no new capture
332
+ // starts while one waits, so frames never queue up and go stale. An
333
+ // in-memory frame holds a camera buffer while it waits: dropping one must
334
+ // release it.
335
+ const pendingFrameRef = (0, _react.useRef)(null);
336
+ // Bumped by `stopCapture` so a capture or a processing pass still running
337
+ // when the loop stops is dropped instead of sent.
338
+ const captureGenerationRef = (0, _react.useRef)(0);
339
+ // No capture starts before this timestamp. See CAPTURE_WARMUP_MS.
340
+ const captureNotBeforeRef = (0, _react.useRef)(0);
162
341
  const framesSentRef = (0, _react.useRef)(0);
163
342
  const watchdogRef = (0, _react.useRef)(null);
164
343
  const finalizingRef = (0, _react.useRef)(false);
344
+ // Set when we are about to show the in-flow retry dialog. Iris often
345
+ // closes with 1000 in the same tick as the terminal WARNING, and that close
346
+ // can beat our own 4001 — without this flag the generic onClose would
347
+ // treat a handled rejection as "socket closed before the step finalized".
348
+ const closingForRetryRef = (0, _react.useRef)(false);
165
349
  const toastTimerRef = (0, _react.useRef)(null);
166
350
  // Tracks the toast currently on screen so we can extend its visibility when
167
351
  // the same message arrives again (instead of dismount/remount, which made
@@ -239,13 +423,23 @@ function LivenessMatchView({
239
423
  watchdogRef.current = null;
240
424
  }
241
425
  }, []);
242
- const stopCapture = (0, _react.useCallback)(() => {
426
+ const clearCaptureTimer = (0, _react.useCallback)(() => {
243
427
  if (captureTimerRef.current) {
244
428
  clearInterval(captureTimerRef.current);
245
429
  captureTimerRef.current = null;
246
430
  }
247
- inFlightRef.current = false;
248
431
  }, []);
432
+ const stopCapture = (0, _react.useCallback)(() => {
433
+ clearCaptureTimer();
434
+ captureGenerationRef.current += 1;
435
+ const pending = pendingFrameRef.current;
436
+ pendingFrameRef.current = null;
437
+ if (pending) releaseFrame(pending.frame);
438
+ // Also recovers from a camera or processing call that never settled: the
439
+ // next loop start must not stay blocked on it.
440
+ captureInFlightRef.current = false;
441
+ processingRef.current = false;
442
+ }, [clearCaptureTimer]);
249
443
 
250
444
  // ── Video upload pipeline (OSDKR-4) ─────────────────────────────────────
251
445
  // Everything below is best-effort: never throws into the caller; never
@@ -375,6 +569,16 @@ function LivenessMatchView({
375
569
  }
376
570
  }, [deleteVideoTemp]);
377
571
  const startVideoRecordingIfEnabled = (0, _react.useCallback)(async () => {
572
+ // Idempotent on purpose: with the recorder now starting at
573
+ // POSITIONING_READY, the first CHALLENGE calls this again, and both paths
574
+ // are legitimate — positioning can also be skipped entirely.
575
+ //
576
+ // Without this guard the second call would replace the two Deferreds below
577
+ // while the first recording is still running. `LivenessCamera` returns
578
+ // early because it already holds a Recorder, so the fresh promises would
579
+ // never settle and the finalize path would await them forever — the
580
+ // "analyzing" hang from OSDKR-23, reintroduced through a different door.
581
+ if (videoOutcomeRef.current === 'recording') return;
378
582
  if (!videoUploadRef.current) {
379
583
  _log.log.info('[Liveness] video skipped: no video_upload in liveness-init');
380
584
  return;
@@ -527,32 +731,36 @@ function LivenessMatchView({
527
731
  finish();
528
732
  })();
529
733
  }, [deleteVideoTemp, onCancel, stopCapture, stopVideoRecordingIfActive, stopWatchdog]);
530
- const captureAndSend = (0, _react.useCallback)(async () => {
531
- if (inFlightRef.current) return;
532
- const ws = wsRef.current;
533
- if (!ws || !ws.isOpen()) return;
534
- inFlightRef.current = true;
734
+ const processAndSendFrame = (0, _react.useCallback)(async (queued, generation) => {
735
+ processingRef.current = true;
736
+ const processStart = Date.now();
535
737
  try {
536
- const photo = await cameraRef.current?.takeFrame();
537
- if (!photo || !ws.isOpen()) return;
538
- // Front-camera frames come back mirrored (vision-camera's default for
539
- // front cam, which we keep so the recorded mp4 has a correct rotation
540
- // matrix — see the `isMirrored` comment in LivenessCamera). For Iris,
541
- // we want the un-mirrored yaw so TURN_LEFT/RIGHT challenges map to
542
- // real-world directions, so we flip the JPEG horizontally here before
543
- // signing and sending.
544
- const compressed = await ImageManipulator.manipulateAsync(photo.filePath.startsWith('file://') ? photo.filePath : `file://${photo.filePath}`, [{
545
- resize: {
546
- width: FRAME_MAX_LONG_EDGE
547
- }
548
- }, {
549
- flip: ImageManipulator.FlipType.Horizontal
550
- }], {
551
- compress: FRAME_QUALITY,
552
- format: ImageManipulator.SaveFormat.JPEG
553
- });
554
- if (!ws.isOpen()) return;
555
- const jpeg = await (0, _jpegFromUri.readJpegFromUri)(compressed.uri);
738
+ const ws = wsRef.current;
739
+ if (!ws || !ws.isOpen()) {
740
+ releaseFrame(queued.frame);
741
+ return;
742
+ }
743
+ const encoded = await encodeFrame(queued.frame);
744
+ const {
745
+ jpeg
746
+ } = encoded;
747
+ // The loop stopped (or the socket closed) while this frame was being
748
+ // processed: drop it rather than send a frame from before the stop.
749
+ if (generation !== captureGenerationRef.current || !ws.isOpen()) return;
750
+ // DIAGNOSTIC (OSDKR-24): one line every 10th frame comparing what the
751
+ // camera captured with what went on the wire, plus how long each
752
+ // pipeline stage took. `warn` on purpose: `info` is silent in the
753
+ // release builds testers run.
754
+ if (framesSentRef.current % 10 === 0) {
755
+ void logCaptureDiagnostics({
756
+ encoded,
757
+ source: queued.frame.kind,
758
+ capturePath: queued.frame.kind === 'file' ? queued.frame.filePath : undefined,
759
+ captureMs: queued.captureMs,
760
+ processMs: Date.now() - processStart,
761
+ challenge: currentChallengeRef.current ?? null
762
+ });
763
+ }
556
764
  const key = hmacRef.current;
557
765
  if (key) {
558
766
  const envelope = (0, _hmac.buildSignedFrameEnvelope)({
@@ -574,16 +782,60 @@ function LivenessMatchView({
574
782
  } catch (err) {
575
783
  _log.log.warn('[Liveness] frame send failed', err);
576
784
  } finally {
577
- inFlightRef.current = false;
785
+ // After a stop, `stopCapture` already reset the pipeline; a stale pass
786
+ // must not touch the state of the one that replaced it.
787
+ if (generation === captureGenerationRef.current) {
788
+ processingRef.current = false;
789
+ const next = pendingFrameRef.current;
790
+ if (next) {
791
+ pendingFrameRef.current = null;
792
+ void processAndSendFrame(next, generation);
793
+ }
794
+ }
578
795
  }
579
796
  }, [sessionId]);
797
+ const captureTick = (0, _react.useCallback)(async () => {
798
+ if (captureInFlightRef.current || pendingFrameRef.current) return;
799
+ if (Date.now() < captureNotBeforeRef.current) return;
800
+ const ws = wsRef.current;
801
+ if (!ws || !ws.isOpen()) return;
802
+ const generation = captureGenerationRef.current;
803
+ captureInFlightRef.current = true;
804
+ const captureStart = Date.now();
805
+ let frame;
806
+ try {
807
+ frame = await cameraRef.current?.takeFrame();
808
+ } catch (err) {
809
+ _log.log.warn('[Liveness] frame capture failed', err);
810
+ } finally {
811
+ if (generation === captureGenerationRef.current) {
812
+ captureInFlightRef.current = false;
813
+ }
814
+ }
815
+ if (!frame) return;
816
+ if (generation !== captureGenerationRef.current) {
817
+ releaseFrame(frame);
818
+ return;
819
+ }
820
+ const queued = {
821
+ frame,
822
+ captureMs: Date.now() - captureStart
823
+ };
824
+ if (processingRef.current) {
825
+ pendingFrameRef.current = queued;
826
+ } else {
827
+ void processAndSendFrame(queued, generation);
828
+ }
829
+ }, [processAndSendFrame]);
580
830
  const startCaptureLoop = (0, _react.useCallback)(ms => {
581
- stopCapture();
831
+ // Only the pacing changes here: frames already in the pipeline keep
832
+ // going, so a challenge switching the fps does not cost a frame.
833
+ clearCaptureTimer();
582
834
  frameMsRef.current = ms;
583
835
  captureTimerRef.current = setInterval(() => {
584
- void captureAndSend();
836
+ void captureTick();
585
837
  }, ms);
586
- }, [captureAndSend, stopCapture]);
838
+ }, [captureTick, clearCaptureTimer]);
587
839
  const adjustFps = (0, _react.useCallback)(ms => {
588
840
  if (frameMsRef.current === ms) return;
589
841
  if (captureTimerRef.current) {
@@ -597,6 +849,7 @@ function LivenessMatchView({
597
849
  return t.liveness.challenge[id] ?? '';
598
850
  }, [t.liveness.challenge]);
599
851
  const presentTerminalRetry = (0, _react.useCallback)((code, message) => {
852
+ closingForRetryRef.current = true;
600
853
  stopCapture();
601
854
  stopWatchdog();
602
855
  try {
@@ -644,14 +897,13 @@ function LivenessMatchView({
644
897
  // failed before the user understood what was being asked.
645
898
  setChallengeText(t.liveness.centerFace);
646
899
  showToast('success', t.liveness.getReady);
900
+ captureNotBeforeRef.current = Date.now() + CAPTURE_WARMUP_MS;
647
901
  startCaptureLoop(FRAME_MS_DEFAULT);
648
- // Start the local mp4 recording in parallel with the frame loop, if
649
- // the backend opted in via `video_upload` in /liveness-init. Pure
650
- // best-effort: any failure here is logged and never blocks liveness.
651
- // Deliberately not awaited — creating the recorder is asynchronous
652
- // in v5 and the frame loop must not wait on it. The function
653
- // swallows its own errors, so the floating promise never rejects.
654
- void startVideoRecordingIfEnabled();
902
+ // Do not start the evidence recorder yet. MiniFAS and positioning
903
+ // run on these first seconds; a photo+video session on Android
904
+ // produced blurry stills (`LOW_SHARPNESS`) and a screen-replay
905
+ // score. Recording starts on POSITIONING_READY (or the first
906
+ // CHALLENGE if positioning is disabled).
655
907
  resetWatchdog();
656
908
  return;
657
909
  }
@@ -668,7 +920,7 @@ function LivenessMatchView({
668
920
  total: msg.totalChallenges
669
921
  };
670
922
  }
671
- adjustFps(ch === 'TURN_LEFT' || ch === 'TURN_RIGHT' ? FRAME_MS_TURN : FRAME_MS_DEFAULT);
923
+ adjustFps(ch === 'TURN_LEFT' || ch === 'TURN_RIGHT' ? FRAME_MS_TURN : ch === 'BLINK' ? FRAME_MS_BLINK : FRAME_MS_DEFAULT);
672
924
  setChallengeText(challengeLabel(ch));
673
925
  // Map distance challenges to an oval-size cue so the viewfinder
674
926
  // shape reinforces the instruction (grows for closer, returns to
@@ -676,6 +928,9 @@ function LivenessMatchView({
676
928
  // oval — the dim mask shouldn't move under a turn / smile / blink.
677
929
  setOvalCue(ch === 'MOVE_CLOSER' ? 'MOVE_CLOSER' : ch === 'MOVE_FARTHER' ? 'MOVE_FARTHER' : 'NEUTRAL');
678
930
  setProgress(0);
931
+ // Positioning skipped or already passed — start the evidence
932
+ // recorder if it is not running yet (idempotent).
933
+ void startVideoRecordingIfEnabled();
679
934
  resetWatchdog();
680
935
  return;
681
936
  }
@@ -736,11 +991,20 @@ function LivenessMatchView({
736
991
  // bar, neutral oval, persistent hint — and let the SAME challenge
737
992
  // re-arrive on its own once the user is well positioned again.
738
993
  if (msg.code === 'CHALLENGE_REPOSITION') {
994
+ const abortedChallenge = currentChallengeRef.current;
739
995
  currentChallengeRef.current = null;
740
996
  adjustFps(FRAME_MS_DEFAULT);
741
997
  setProgress(null);
742
998
  setOvalCue('NEUTRAL');
743
- const repositionText = msg.message ?? t.liveness.repositioning;
999
+ // A MOVE_FARTHER abort is the one case where the orchestrator's
1000
+ // generic "center your face and improve the lighting" sends the
1001
+ // user the wrong way (OSDKR-24). Moving away shrinks the face, and
1002
+ // with it the sharpness Iris measures, until the mid-challenge
1003
+ // check aborts; the user then has to come back closer before
1004
+ // positioning reopens. On an Edge 30 Neo they stayed at the far
1005
+ // distance for 43 s. Our own copy overrides the server text here
1006
+ // until IRIS-31 stops that abort at the source.
1007
+ const repositionText = abortedChallenge === 'MOVE_FARTHER' ? t.liveness.repositioningAfterMoveFarther : msg.message ?? t.liveness.repositioning;
744
1008
  setChallengeText(repositionText);
745
1009
  showToast('warning', repositionText);
746
1010
  resetWatchdog();
@@ -796,6 +1060,9 @@ function LivenessMatchView({
796
1060
  const baseText = msg.message ?? codedFallback;
797
1061
  const text = isPositioningReady ? t.liveness.positioningReady : typeof msg.consecutiveMisses === 'number' && msg.consecutiveMisses >= 3 ? t.liveness.warningConsecutiveMisses.replace('{n}', String(msg.consecutiveMisses)).concat(' — ', baseText) : baseText;
798
1062
  showToast(isPositioningReady ? 'success' : 'warning', text);
1063
+ if (isPositioningReady) {
1064
+ void startVideoRecordingIfEnabled();
1065
+ }
799
1066
  resetWatchdog();
800
1067
  return;
801
1068
  }
@@ -895,6 +1162,7 @@ function LivenessMatchView({
895
1162
  setRetry(null);
896
1163
  setStatusText(t.liveness.connecting);
897
1164
  finalizingRef.current = false;
1165
+ closingForRetryRef.current = false;
898
1166
  framesSentRef.current = 0;
899
1167
  currentChallengeRef.current = null;
900
1168
  lastChallengeMetaRef.current = null;
@@ -972,15 +1240,30 @@ function LivenessMatchView({
972
1240
  // — this handler is registered via closure on a stale render,
973
1241
  // so `retry` reads `null` even when we just called `setRetry`.
974
1242
  // The close code is reliable: we always pair 4001 with the
975
- // retry-dialog mount.
976
- if (code === 4001) return;
1243
+ // retry-dialog mount. `closingForRetryRef` covers the race where
1244
+ // Iris's own 1000 arrives first (it always closes NORMAL after a
1245
+ // terminal WARNING).
1246
+ if (code === 4001 || closingForRetryRef.current) return;
977
1247
  stopCapture();
978
- stopWatchdog();
979
- if (code === 1000) return;
980
- failWith({
981
- code: _types.SdkErrorCode.LIVENESS_FAILED,
982
- message: `Iris WebSocket closed before completion (code=${code}${reason ? `, reason=${reason}` : ''}).`
1248
+
1249
+ // Reaching here means the socket closed and the step never
1250
+ // finalized, so we do not know how the session ended (OSDKR-23).
1251
+ //
1252
+ // A close code cannot tell us: Iris closes with 1000 after a
1253
+ // successful SESSION_COMPLETE, after CHALLENGE_NOT_CONFIRMED, and
1254
+ // after SPOOF_RISK_HIGH alike. It always sends the deciding message
1255
+ // immediately before closing, so a 1000 here means we lost it.
1256
+ //
1257
+ // This used to `stopWatchdog()` and then return on 1000, which left
1258
+ // the step on the "analyzing" overlay forever with every safety net
1259
+ // disarmed. Route the user into the same recovery a terminal warning
1260
+ // uses instead: the session did not complete as far as we can tell,
1261
+ // and offering a retry is both honest and actionable.
1262
+ _log.log.warn('[Liveness] socket closed before the step finalized', {
1263
+ code,
1264
+ reason
983
1265
  });
1266
+ presentTerminalRetry('CONNECTION_CLOSED', t.liveness.terminalRetryFallback);
984
1267
  }
985
1268
  });
986
1269
  } catch (err) {
@@ -992,7 +1275,7 @@ function LivenessMatchView({
992
1275
  return;
993
1276
  }
994
1277
  wsRef.current = connection;
995
- }, [api, calibrationLabel, failWith, handleWsMessage, locale, retry, sessionId, stopCapture, stopWatchdog, t.liveness.connecting, t.liveness.preparingCamera]);
1278
+ }, [api, calibrationLabel, failWith, handleWsMessage, locale, presentTerminalRetry, retry, sessionId, stopCapture, t.liveness.connecting, t.liveness.preparingCamera, t.liveness.terminalRetryFallback]);
996
1279
 
997
1280
  // Re-run after a terminal retry — same cleanup as start, but reuses the
998
1281
  // mounted camera (no DOM teardown).