@velion-la/onboarding-sdk-react-native 1.0.0-beta.9 → 1.0.1

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 (59) hide show
  1. package/CHANGELOG.md +16 -1
  2. package/lib/commonjs/camera/DocumentCapture.js +78 -26
  3. package/lib/commonjs/camera/DocumentCapture.js.map +1 -1
  4. package/lib/commonjs/i18n/strings/en.js +3 -2
  5. package/lib/commonjs/i18n/strings/en.js.map +1 -1
  6. package/lib/commonjs/i18n/strings/es.js +3 -2
  7. package/lib/commonjs/i18n/strings/es.js.map +1 -1
  8. package/lib/commonjs/steps/DocumentsOcrStep.js +152 -35
  9. package/lib/commonjs/steps/DocumentsOcrStep.js.map +1 -1
  10. package/lib/commonjs/steps/PhoneContactStep.js +10 -4
  11. package/lib/commonjs/steps/PhoneContactStep.js.map +1 -1
  12. package/lib/commonjs/steps/PhoneOtpStep.js +17 -6
  13. package/lib/commonjs/steps/PhoneOtpStep.js.map +1 -1
  14. package/lib/commonjs/ui/StepShell.js +122 -12
  15. package/lib/commonjs/ui/StepShell.js.map +1 -1
  16. package/lib/commonjs/ui/overlays/ProgressBar.js +8 -2
  17. package/lib/commonjs/ui/overlays/ProgressBar.js.map +1 -1
  18. package/lib/commonjs/utils/documentCrop.js +136 -0
  19. package/lib/commonjs/utils/documentCrop.js.map +1 -0
  20. package/lib/module/camera/DocumentCapture.js +78 -26
  21. package/lib/module/camera/DocumentCapture.js.map +1 -1
  22. package/lib/module/i18n/strings/en.js +3 -2
  23. package/lib/module/i18n/strings/en.js.map +1 -1
  24. package/lib/module/i18n/strings/es.js +3 -2
  25. package/lib/module/i18n/strings/es.js.map +1 -1
  26. package/lib/module/steps/DocumentsOcrStep.js +152 -34
  27. package/lib/module/steps/DocumentsOcrStep.js.map +1 -1
  28. package/lib/module/steps/PhoneContactStep.js +10 -4
  29. package/lib/module/steps/PhoneContactStep.js.map +1 -1
  30. package/lib/module/steps/PhoneOtpStep.js +17 -6
  31. package/lib/module/steps/PhoneOtpStep.js.map +1 -1
  32. package/lib/module/ui/StepShell.js +122 -13
  33. package/lib/module/ui/StepShell.js.map +1 -1
  34. package/lib/module/ui/overlays/ProgressBar.js +8 -1
  35. package/lib/module/ui/overlays/ProgressBar.js.map +1 -1
  36. package/lib/module/utils/documentCrop.js +129 -0
  37. package/lib/module/utils/documentCrop.js.map +1 -0
  38. package/lib/typescript/camera/DocumentCapture.d.ts +20 -8
  39. package/lib/typescript/camera/DocumentCapture.d.ts.map +1 -1
  40. package/lib/typescript/i18n/strings/en.d.ts.map +1 -1
  41. package/lib/typescript/i18n/strings/es.d.ts +1 -0
  42. package/lib/typescript/i18n/strings/es.d.ts.map +1 -1
  43. package/lib/typescript/steps/DocumentsOcrStep.d.ts +8 -6
  44. package/lib/typescript/steps/DocumentsOcrStep.d.ts.map +1 -1
  45. package/lib/typescript/ui/StepShell.d.ts.map +1 -1
  46. package/lib/typescript/ui/overlays/ProgressBar.d.ts +6 -0
  47. package/lib/typescript/ui/overlays/ProgressBar.d.ts.map +1 -1
  48. package/lib/typescript/utils/documentCrop.d.ts +78 -0
  49. package/lib/typescript/utils/documentCrop.d.ts.map +1 -0
  50. package/package.json +1 -1
  51. package/src/camera/DocumentCapture.tsx +76 -25
  52. package/src/i18n/strings/en.ts +3 -2
  53. package/src/i18n/strings/es.ts +3 -2
  54. package/src/steps/DocumentsOcrStep.tsx +180 -32
  55. package/src/steps/PhoneContactStep.tsx +9 -3
  56. package/src/steps/PhoneOtpStep.tsx +14 -4
  57. package/src/ui/StepShell.tsx +114 -12
  58. package/src/ui/overlays/ProgressBar.tsx +8 -1
  59. package/src/utils/documentCrop.ts +159 -0
@@ -5,13 +5,15 @@
5
5
  * intro → captureFront → reviewFront → captureBack → reviewBack →
6
6
  * POST /documents-init → PUT image/jpeg × 2 → POST /documents-verify → done.
7
7
  *
8
- * No edge detection / OpenCV port (intentional MVP scope per the brief). The
9
- * camera shows the ID-1 frame guide and the user fills it; the backend OCR
10
- * pipeline handles cropping.
8
+ * Crop: on capture we receive the on-screen guide rectangle and crop the photo
9
+ * to it (OSDKR-2) — a geometric crop to the visible ID-1 frame, NOT edge
10
+ * detection / OpenCV. This trims the camera background, improves OCR framing
11
+ * and shrinks the upload. The backend's Document AI still runs OCR + its own
12
+ * face crop on top, so we keep a safety margin around the guide.
11
13
  *
12
- * Compression: vision-camera writes a high-quality JPEG. We re-compress with
13
- * `expo-image-manipulator` before upload so we keep the payload under the
14
- * 5 MB ceiling Velion's storage layer expects.
14
+ * Compression: vision-camera writes a high-quality JPEG. After cropping we
15
+ * resize + re-compress with `expo-image-manipulator` before upload so we keep
16
+ * the payload under the 5 MB ceiling Velion's storage layer expects.
15
17
  */
16
18
  import type { StepDeps, StepModule } from './types';
17
19
  export declare class DocumentsOcrStep implements StepModule {
@@ -1 +1 @@
1
- {"version":3,"file":"DocumentsOcrStep.d.ts","sourceRoot":"","sources":["../../../src/steps/DocumentsOcrStep.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAiCH,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAsBpD,qBAAa,gBAAiB,YAAW,UAAU;IAKrC,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;IA0BpB,OAAO,IAAI,IAAI;CAIhB"}
1
+ {"version":3,"file":"DocumentsOcrStep.d.ts","sourceRoot":"","sources":["../../../src/steps/DocumentsOcrStep.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAwCH,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAsBpD,qBAAa,gBAAiB,YAAW,UAAU;IAKrC,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;IA0BpB,OAAO,IAAI,IAAI;CAIhB"}
@@ -1 +1 @@
1
- {"version":3,"file":"StepShell.d.ts","sourceRoot":"","sources":["../../../src/ui/StepShell.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAavC,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IACjC,QAAQ,EAAE,SAAS,CAAC;IACpB,kFAAkF;IAClF,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACpC;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;IAClC,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,kFAAkF;IAClF,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACpC;AAED,wBAAgB,SAAS,CAAC,EACxB,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,aAAoB,EACpB,MAAM,EACN,SAAmB,EACnB,YAAoB,GACrB,EAAE,cAAc,+BAiEhB"}
1
+ {"version":3,"file":"StepShell.d.ts","sourceRoot":"","sources":["../../../src/ui/StepShell.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAqBvC,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IACjC,QAAQ,EAAE,SAAS,CAAC;IACpB,kFAAkF;IAClF,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACpC;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;IAClC,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,kFAAkF;IAClF,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACpC;AAED,wBAAgB,SAAS,CAAC,EACxB,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,aAAoB,EACpB,MAAM,EACN,SAAmB,EACnB,YAAoB,GACrB,EAAE,cAAc,+BA2IhB"}
@@ -6,6 +6,12 @@
6
6
  * Animated with `Animated.timing` (driver: native) so we don't pull in
7
7
  * Reanimated yet; respects `useReducedMotion()`.
8
8
  */
9
+ /**
10
+ * Height of the progress track, in px. Exported so layout-aware chrome (e.g.
11
+ * `StepShell`'s fixed back-button strip) can sit flush below the bar without
12
+ * duplicating the magic number.
13
+ */
14
+ export declare const PROGRESS_BAR_HEIGHT = 4;
9
15
  export interface ProgressBarProps {
10
16
  /** 0–100. Components compute the trickling logic externally and pass it in. */
11
17
  value: number;
@@ -1 +1 @@
1
- {"version":3,"file":"ProgressBar.d.ts","sourceRoot":"","sources":["../../../../src/ui/overlays/ProgressBar.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,WAAW,CAAC,EAAE,KAAK,EAAE,MAAc,EAAE,EAAE,gBAAgB,+BA+CtE;AAKD;;;;GAIG;AACH,eAAO,MAAM,YAAY;kBACT,MAAM,GAAG,MAAM;gBAGjB,MAAM;aAGT,MAAM;CAGhB,CAAC"}
1
+ {"version":3,"file":"ProgressBar.d.ts","sourceRoot":"","sources":["../../../../src/ui/overlays/ProgressBar.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,WAAW,CAAC,EAAE,KAAK,EAAE,MAAc,EAAE,EAAE,gBAAgB,+BA+CtE;AAKD;;;;GAIG;AACH,eAAO,MAAM,YAAY;kBACT,MAAM,GAAG,MAAM;gBAGjB,MAAM;aAGT,MAAM;CAGhB,CAAC"}
@@ -0,0 +1,78 @@
1
+ /**
2
+ * @fileoverview Geometry for the document capture guide + crop.
3
+ *
4
+ * Two pure helpers, shared between the camera overlay and the post-capture
5
+ * crop so the pixels we keep are *exactly* the rectangle the user framed:
6
+ *
7
+ * - `computeCutout` — the on-screen ID-1 guide rectangle (screen px).
8
+ * - `computeGuideCropRect` — maps that guide rectangle into the captured
9
+ * photo's pixel space, compensating for the camera preview's `cover` fit
10
+ * (the preview center-crops the sensor frame to the screen aspect ratio).
11
+ *
12
+ * This is a *geometric* crop to a fixed guide, NOT edge detection / OpenCV —
13
+ * we never inspect pixels. The backend's Document AI still runs OCR and its
14
+ * own face crop on top, so we keep a safety margin around the guide to avoid
15
+ * clipping the document (or the portrait the backend needs).
16
+ */
17
+ import type { DocumentOrientation } from '../types';
18
+ export interface CutoutRect {
19
+ left: number;
20
+ top: number;
21
+ width: number;
22
+ height: number;
23
+ }
24
+ export interface PixelRect {
25
+ x: number;
26
+ y: number;
27
+ width: number;
28
+ height: number;
29
+ }
30
+ /** Default crop margin: expand each side of the guide by this fraction of the
31
+ * guide size, so a document slightly overflowing the frame isn't clipped. */
32
+ export declare const DEFAULT_CROP_MARGIN = 0.07;
33
+ /**
34
+ * The on-screen guide rectangle, in screen pixels. Mirrors what the mask
35
+ * overlay draws so the crop matches the visible cutout exactly.
36
+ */
37
+ export declare function computeCutout(screenW: number, screenH: number, orientation: DocumentOrientation): CutoutRect;
38
+ /**
39
+ * Map the on-screen guide rectangle into the captured photo's pixel space.
40
+ *
41
+ * The preview renders the photo with `cover` fit: the sensor frame is scaled
42
+ * up until it fills the screen and the overflow is center-cropped. So a screen
43
+ * point `(sx, sy)` maps to photo pixel `((W_img - W_screen/s)/2 + sx/s, …)`,
44
+ * where `s = max(W_screen/W_img, H_screen/H_img)`.
45
+ *
46
+ * `imageW`/`imageH` MUST be the photo's *display* (orientation-normalized)
47
+ * dimensions — i.e. portrait when the device is portrait — not the raw sensor
48
+ * dimensions, which are often landscape with an EXIF rotation flag.
49
+ *
50
+ * The result is expanded by `margin` (fraction of the mapped guide) and
51
+ * clamped to the image bounds, then rounded to integers (the manipulator
52
+ * rejects fractional crop rects).
53
+ */
54
+ /**
55
+ * Whether the guide rectangle can be mapped onto the photo at all (OSDKR-13).
56
+ *
57
+ * `computeGuideCropRect` inverts a `cover` fit, which only makes sense when the
58
+ * screen and the photo are in the *same* orientation space — the photo is the
59
+ * preview the guide was drawn over. If the two disagree (a portrait screen and
60
+ * a landscape photo), something upstream rotated the capture and any rect we
61
+ * compute would address the wrong pixels. Callers should skip the crop and
62
+ * upload the full photo instead of shipping a garbage region.
63
+ */
64
+ export declare function isGuideSpaceConsistent(params: {
65
+ screenW: number;
66
+ screenH: number;
67
+ imageW: number;
68
+ imageH: number;
69
+ }): boolean;
70
+ export declare function computeGuideCropRect(params: {
71
+ screenW: number;
72
+ screenH: number;
73
+ imageW: number;
74
+ imageH: number;
75
+ cutout: CutoutRect;
76
+ margin?: number;
77
+ }): PixelRect;
78
+ //# sourceMappingURL=documentCrop.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"documentCrop.d.ts","sourceRoot":"","sources":["../../../src/utils/documentCrop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAEpD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAYD;8EAC8E;AAC9E,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,mBAAmB,GAC/B,UAAU,CAiBZ;AAED;;;;;;;;;;;;;;;GAeG;AACH;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAIV;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,SAAS,CAwCZ"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@velion-la/onboarding-sdk-react-native",
3
- "version": "1.0.0-beta.9",
3
+ "version": "1.0.1",
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",
@@ -5,12 +5,12 @@
5
5
  * triggers `takePhoto()` with `qualityPrioritization: 'balanced'`; the file
6
6
  * URI is returned to the caller via `onCaptured`.
7
7
  *
8
- * Visual: dark scrim with a transparent rectangular cutout (ID-1 16:10 ratio
9
- * by default). The cutout is the visible-only guide — we do NOT crop the
10
- * image client-side because the server's OCR pipeline rejects soft crops.
11
- * The user is asked to fill the frame; the backend handles edge detection.
12
- *
13
- * No edge detection / OpenCV port (intentional MVP scope per the brief).
8
+ * Visual: dark scrim with a transparent rectangular cutout (ID-1 ratio). The
9
+ * cutout is both the visible guide AND the crop region: on capture we hand the
10
+ * caller the guide rectangle so the photo can be cropped to exactly what the
11
+ * user framed (OSDKR-2). This is a geometric crop to a fixed guide — NOT edge
12
+ * detection / OpenCV; we never inspect pixels. The backend's Document AI still
13
+ * runs OCR and its own face crop on top.
14
14
  */
15
15
 
16
16
  import { useCallback, useEffect, useRef, useState } from 'react';
@@ -33,6 +33,17 @@ import type { DocumentOrientation, DocumentSide } from '../types';
33
33
  import { useTheme, withAlpha } from '../ui/theme';
34
34
  import { Button } from '../ui/primitives/Button';
35
35
  import { useSafeAreaInsets } from '../utils/useSafeAreaInsets';
36
+ import { computeCutout, type CutoutRect } from '../utils/documentCrop';
37
+
38
+ /**
39
+ * Geometry of the on-screen guide at capture time, handed to `onCaptured` so
40
+ * the photo can be cropped to exactly what the user framed.
41
+ */
42
+ export interface CaptureGuide {
43
+ cutout: CutoutRect;
44
+ screenW: number;
45
+ screenH: number;
46
+ }
36
47
 
37
48
  export interface DocumentCaptureProps {
38
49
  side: DocumentSide;
@@ -47,7 +58,13 @@ export interface DocumentCaptureProps {
47
58
  retryLabel: string;
48
59
  /** Localized "Cancel" / back label. */
49
60
  cancelLabel: string;
50
- onCaptured: (photo: PhotoFile, side: DocumentSide) => void;
61
+ /** Localized label shown over the camera while the shot is processed. */
62
+ processingLabel: string;
63
+ onCaptured: (
64
+ photo: PhotoFile,
65
+ side: DocumentSide,
66
+ guide: CaptureGuide,
67
+ ) => void | Promise<void>;
51
68
  onCancel: () => void;
52
69
  }
53
70
 
@@ -59,11 +76,13 @@ export function DocumentCapture({
59
76
  permissionDeniedLabel,
60
77
  retryLabel,
61
78
  cancelLabel,
79
+ processingLabel,
62
80
  onCaptured,
63
81
  onCancel,
64
82
  }: DocumentCaptureProps) {
65
83
  const theme = useTheme();
66
84
  const insets = useSafeAreaInsets();
85
+ const { width: screenW, height: screenH } = useWindowDimensions();
67
86
  const cameraRef = useRef<Camera>(null);
68
87
  // Cross-platform back-camera selection.
69
88
  //
@@ -157,13 +176,19 @@ export function DocumentCapture({
157
176
  flash: 'off',
158
177
  enableShutterSound: false,
159
178
  });
160
- onCaptured(photo, side);
179
+ // Await the caller's crop/compress so the processing overlay stays up
180
+ // for the whole capture→preview gap (a few seconds), giving the user
181
+ // feedback instead of an idle camera. On success the parent flips phase
182
+ // and this component unmounts; on failure / "stay on capture" the finally
183
+ // re-enables the shutter.
184
+ const cutout = computeCutout(screenW, screenH, orientation);
185
+ await onCaptured(photo, side, { cutout, screenW, screenH });
161
186
  } catch (err) {
162
187
  setError(err instanceof Error ? err.message : String(err));
163
188
  } finally {
164
189
  setShooting(false);
165
190
  }
166
- }, [onCaptured, side, shooting]);
191
+ }, [onCaptured, side, shooting, orientation, screenW, screenH]);
167
192
 
168
193
  if (!hasPermission) {
169
194
  return (
@@ -227,6 +252,21 @@ export function DocumentCapture({
227
252
  device={device}
228
253
  photo
229
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"
265
+ // Explicit `cover`: the guide-crop math in `computeGuideCropRect`
266
+ // assumes the preview center-crops the sensor frame to the screen
267
+ // aspect ratio. `cover` is vision-camera's default, but we pin it so
268
+ // the crop never silently drifts if that default changes.
269
+ resizeMode="cover"
230
270
  enableZoomGesture={false}
231
271
  isActive
232
272
  />
@@ -285,6 +325,12 @@ export function DocumentCapture({
285
325
  />
286
326
  </Pressable>
287
327
  </View>
328
+ {shooting ? (
329
+ <View style={styles.processingOverlay}>
330
+ <ActivityIndicator color="#FFFFFF" size="large" />
331
+ <Text style={styles.processingText}>{processingLabel}</Text>
332
+ </View>
333
+ ) : null}
288
334
  </View>
289
335
  );
290
336
  }
@@ -295,8 +341,6 @@ interface MaskProps {
295
341
  orientation: DocumentOrientation;
296
342
  }
297
343
 
298
- const CUTOUT_WIDTH_RATIO = 0.85; // 85% of screen width
299
- const CUTOUT_MAX_HEIGHT_RATIO = 0.62; // never taller than 62% of screen height
300
344
  const CORNER_LENGTH = 28;
301
345
  const CORNER_THICKNESS = 3;
302
346
  /**
@@ -309,20 +353,14 @@ const DIM_COLOR = 'rgba(0,0,0,0.55)';
309
353
 
310
354
  function DocumentMaskOverlay({ orientation }: MaskProps) {
311
355
  const { width: screenW, height: screenH } = useWindowDimensions();
312
- const aspectRatio = orientation === 'portrait' ? 0.625 : 1.586;
313
-
314
- // Compute the cutout proportionally. Width is the primary dimension; if
315
- // the resulting height would overflow the screen budget (mostly portrait
316
- // ID-1 = 0.625 aspect on tall phones), shrink it back to fit.
317
- let cutoutW = screenW * CUTOUT_WIDTH_RATIO;
318
- let cutoutH = cutoutW / aspectRatio;
319
- const maxH = screenH * CUTOUT_MAX_HEIGHT_RATIO;
320
- if (cutoutH > maxH) {
321
- cutoutH = maxH;
322
- cutoutW = cutoutH * aspectRatio;
323
- }
324
- const left = (screenW - cutoutW) / 2;
325
- const top = (screenH - cutoutH) / 2;
356
+ // Shared with the post-capture crop (`computeGuideCropRect`) so the dimmed
357
+ // cutout the user sees and the pixels we keep are the exact same rectangle.
358
+ const {
359
+ left,
360
+ top,
361
+ width: cutoutW,
362
+ height: cutoutH,
363
+ } = computeCutout(screenW, screenH, orientation);
326
364
  const R = CUTOUT_RADIUS;
327
365
 
328
366
  // SVG mask: opaque outer rect minus a rounded inner rect. The mask paints
@@ -511,4 +549,17 @@ const styles = StyleSheet.create({
511
549
  borderColor: '#FFFFFF',
512
550
  backgroundColor: 'transparent',
513
551
  },
552
+ processingOverlay: {
553
+ ...StyleSheet.absoluteFillObject,
554
+ alignItems: 'center',
555
+ justifyContent: 'center',
556
+ gap: 14,
557
+ backgroundColor: 'rgba(0,0,0,0.6)',
558
+ },
559
+ processingText: {
560
+ color: '#FFFFFF',
561
+ fontSize: 15,
562
+ fontWeight: '600',
563
+ textAlign: 'center',
564
+ },
514
565
  });
@@ -22,7 +22,7 @@ export const EN: StringsTable = {
22
22
  human_basic_info: {
23
23
  title: 'Personal information',
24
24
  subtitle:
25
- 'Enter your name and ID exactly as shown on your official identification.',
25
+ 'Enter your name and ID exactly as shown on your identification.',
26
26
  givenNames: 'Given name(s)',
27
27
  familyNames: 'Family name(s)',
28
28
  idType: 'ID type',
@@ -78,7 +78,7 @@ export const EN: StringsTable = {
78
78
  tax_info: {
79
79
  title: 'Tax information',
80
80
  subtitle:
81
- 'Enter your taxpayer category and tax ID as registered with ARCA or the equivalent authority.',
81
+ 'Complete your tax information to help us get to know you better.',
82
82
  taxpayerType: 'Taxpayer category',
83
83
  taxpayerIdType: 'Tax identification type',
84
84
  taxpayerId: 'Identification number',
@@ -216,6 +216,7 @@ export const EN: StringsTable = {
216
216
  confirmBtn: 'Confirm',
217
217
  confirmFront: 'Confirm front',
218
218
  confirmBack: 'Confirm back',
219
+ processing: 'Processing image…',
219
220
  initializing: 'Preparing capture…',
220
221
  uploadingFront: 'Uploading front…',
221
222
  uploadingBack: 'Uploading back…',
@@ -25,7 +25,7 @@ export const ES = {
25
25
  human_basic_info: {
26
26
  title: 'Datos personales',
27
27
  subtitle:
28
- 'Ingresá tu nombre y documento tal como figuran en tu identificación oficial.',
28
+ 'Ingresá tu nombre y documento tal como figuran en tu identificación.',
29
29
  givenNames: 'Nombre(s)',
30
30
  familyNames: 'Apellido(s)',
31
31
  idType: 'Tipo de documento',
@@ -81,7 +81,7 @@ export const ES = {
81
81
  tax_info: {
82
82
  title: 'Información fiscal',
83
83
  subtitle:
84
- 'Indicá tu categoría e identificación tributaria según conste en ARCA u organismo equivalente.',
84
+ 'Completá tu información fiscal para ayudarnos a conocerte mejor.',
85
85
  taxpayerType: 'Categoría fiscal',
86
86
  taxpayerIdType: 'Tipo de identificación fiscal',
87
87
  taxpayerId: 'Número de identificación',
@@ -219,6 +219,7 @@ export const ES = {
219
219
  confirmBtn: 'Confirmar',
220
220
  confirmFront: 'Confirmar frente',
221
221
  confirmBack: 'Confirmar dorso',
222
+ processing: 'Procesando imagen…',
222
223
  initializing: 'Preparando captura…',
223
224
  uploadingFront: 'Subiendo frente…',
224
225
  uploadingBack: 'Subiendo dorso…',
@@ -5,13 +5,15 @@
5
5
  * intro → captureFront → reviewFront → captureBack → reviewBack →
6
6
  * POST /documents-init → PUT image/jpeg × 2 → POST /documents-verify → done.
7
7
  *
8
- * No edge detection / OpenCV port (intentional MVP scope per the brief). The
9
- * camera shows the ID-1 frame guide and the user fills it; the backend OCR
10
- * pipeline handles cropping.
8
+ * Crop: on capture we receive the on-screen guide rectangle and crop the photo
9
+ * to it (OSDKR-2) — a geometric crop to the visible ID-1 frame, NOT edge
10
+ * detection / OpenCV. This trims the camera background, improves OCR framing
11
+ * and shrinks the upload. The backend's Document AI still runs OCR + its own
12
+ * face crop on top, so we keep a safety margin around the guide.
11
13
  *
12
- * Compression: vision-camera writes a high-quality JPEG. We re-compress with
13
- * `expo-image-manipulator` before upload so we keep the payload under the
14
- * 5 MB ceiling Velion's storage layer expects.
14
+ * Compression: vision-camera writes a high-quality JPEG. After cropping we
15
+ * resize + re-compress with `expo-image-manipulator` before upload so we keep
16
+ * the payload under the 5 MB ceiling Velion's storage layer expects.
15
17
  */
16
18
 
17
19
  import { useCallback, useEffect, useMemo, useState } from 'react';
@@ -23,7 +25,10 @@ import {
23
25
  Text,
24
26
  View,
25
27
  } from 'react-native';
26
- import * as ImageManipulator from 'expo-image-manipulator';
28
+ import {
29
+ ImageManipulator as ImageManipulatorModule,
30
+ SaveFormat,
31
+ } from 'expo-image-manipulator';
27
32
  import type { PhotoFile } from 'react-native-vision-camera';
28
33
  import {
29
34
  SdkErrorCode,
@@ -43,7 +48,11 @@ import { useTheme, mixHex } from '../ui/theme';
43
48
  import { getStrings } from '../i18n';
44
49
  import { resolveCaptureModeFromStepConfig } from '../utils/stepConfig';
45
50
  import { log } from '../utils/log';
46
- import { DocumentCapture } from '../camera/DocumentCapture';
51
+ import { DocumentCapture, type CaptureGuide } from '../camera/DocumentCapture';
52
+ import {
53
+ computeGuideCropRect,
54
+ isGuideSpaceConsistent,
55
+ } from '../utils/documentCrop';
47
56
  import type { ApiCaller } from '../transport/api';
48
57
  import type { StepDeps, StepModule } from './types';
49
58
  import { toSubmissionError } from './_shared';
@@ -151,11 +160,16 @@ function DocumentsOcrView({
151
160
  const [bannerError, setBannerError] = useState<string | null>(null);
152
161
  const [busyLabel, setBusyLabel] = useState<string | null>(null);
153
162
  const [retry, setRetry] = useState<{ message: string } | null>(null);
163
+ // Measured size of the preview area, used to fit the framed card to the
164
+ // capture's exact aspect ratio (no empty letterbox bands around the crop).
165
+ const [previewBox, setPreviewBox] = useState<{ w: number; h: number } | null>(
166
+ null,
167
+ );
154
168
 
155
169
  const handleCaptured = useCallback(
156
- async (photo: PhotoFile, side: DocumentSide) => {
170
+ async (photo: PhotoFile, side: DocumentSide, guide: CaptureGuide) => {
157
171
  try {
158
- const compressed = await compressJpeg(photo.path);
172
+ const compressed = await compressJpeg(photo.path, guide);
159
173
  if (compressed.byteLength > MAX_BYTES) {
160
174
  setBannerError(t.documents_ocr.fileTooLarge);
161
175
  // Stay on the capture phase so the user can retake immediately.
@@ -249,6 +263,7 @@ function DocumentsOcrView({
249
263
  permissionDeniedLabel={t.documents_ocr.cameraPermissionDenied}
250
264
  retryLabel={t.documents_ocr.cameraTryAgain}
251
265
  cancelLabel={t.common.cancel}
266
+ processingLabel={t.documents_ocr.processing}
252
267
  onCancel={() =>
253
268
  setPhase(side === 'FRONT' ? 'intro' : 'reviewFront')
254
269
  }
@@ -270,12 +285,39 @@ function DocumentsOcrView({
270
285
  <Text style={[styles.reviewTitle, { color: theme.textColor }]}>
271
286
  {side === 'FRONT' ? t.documents_ocr.frontTitle : t.documents_ocr.backTitle}
272
287
  </Text>
273
- <View style={styles.previewWrap}>
274
- <Image
275
- source={{ uri: captured.uri }}
276
- style={styles.preview}
277
- resizeMode="contain"
278
- />
288
+ <View
289
+ style={styles.previewWrap}
290
+ onLayout={(e) =>
291
+ setPreviewBox({
292
+ w: e.nativeEvent.layout.width,
293
+ h: e.nativeEvent.layout.height,
294
+ })
295
+ }
296
+ >
297
+ {previewBox ? (
298
+ <View
299
+ style={[
300
+ styles.previewCard,
301
+ fitContain(
302
+ captured.width / captured.height,
303
+ previewBox.w,
304
+ previewBox.h,
305
+ ),
306
+ {
307
+ borderColor: theme.borderColor,
308
+ borderRadius: theme.borderRadiusPx,
309
+ },
310
+ ]}
311
+ >
312
+ <Image
313
+ source={{ uri: captured.uri }}
314
+ style={styles.preview}
315
+ // Card matches the capture's aspect ratio exactly, so `cover`
316
+ // fills it edge to edge with no distortion and no bands.
317
+ resizeMode="cover"
318
+ />
319
+ </View>
320
+ ) : null}
279
321
  </View>
280
322
  {bannerError ? <Banner message={bannerError} /> : null}
281
323
  <View style={styles.reviewActions}>
@@ -370,22 +412,99 @@ function DocumentsOcrView({
370
412
  );
371
413
  }
372
414
 
373
- async function compressJpeg(uri: string): Promise<CapturedSide> {
374
- // Vision-camera produces 4 K JPEGs on modern phones — well past the 5 MB
375
- // budget. Resize the long edge to 1800 px and recompress to ~78% quality;
376
- // empirically that lands at < 600 KB while keeping OCR-grade legibility.
377
- const result = await ImageManipulator.manipulateAsync(
378
- normalizeFileUri(uri),
379
- [{ resize: { width: MAX_LONG_EDGE } }],
380
- { compress: COMPRESS_QUALITY, format: ImageManipulator.SaveFormat.JPEG },
381
- );
382
- const byteLength = await fetchByteLength(result.uri);
383
- return {
384
- uri: result.uri,
385
- width: result.width,
386
- height: result.height,
387
- byteLength,
388
- };
415
+ async function compressJpeg(
416
+ uri: string,
417
+ guide: CaptureGuide,
418
+ ): Promise<CapturedSide> {
419
+ const source = normalizeFileUri(uri);
420
+
421
+ // Load the photo once and take its dimensions from the *loaded* image, so
422
+ // the crop rectangle and the pixels it addresses come from the same decode
423
+ // with the EXIF orientation already applied (iOS fixes the orientation on
424
+ // load, Glide does on Android). Reading the size through a different API
425
+ // than the one that crops left room for the two to disagree.
426
+ //
427
+ // We crop strictly to the on-screen guide rectangle the user centred the
428
+ // document in; we never inspect pixels and we never rotate based on how the
429
+ // phone was held — `DocumentCapture` pins `outputOrientation="preview"` so
430
+ // the capture always comes back in the orientation the user framed.
431
+ const loadContext = ImageManipulatorModule.manipulate(source);
432
+ const loaded = await loadContext.renderAsync();
433
+ const context = ImageManipulatorModule.manipulate(loaded);
434
+
435
+ try {
436
+ // Sanity check before trusting the screen→photo mapping (OSDKR-13). If the
437
+ // photo came back in a different orientation than the screen the guide was
438
+ // drawn on, the mapping is meaningless: upload the full photo (the backend
439
+ // OCR handles an uncropped ID) instead of an arbitrary region.
440
+ const canCrop = isGuideSpaceConsistent({
441
+ screenW: guide.screenW,
442
+ screenH: guide.screenH,
443
+ imageW: loaded.width,
444
+ imageH: loaded.height,
445
+ });
446
+ if (!canCrop) {
447
+ log.info(
448
+ '[DocumentsOCR] guide/photo orientation mismatch — skipping crop',
449
+ {
450
+ screenW: guide.screenW,
451
+ screenH: guide.screenH,
452
+ imageW: loaded.width,
453
+ imageH: loaded.height,
454
+ },
455
+ );
456
+ }
457
+
458
+ // Crop to the guide, then resize the long edge to MAX_LONG_EDGE (never
459
+ // upscale — the crop can leave a small region) and recompress to ~78%.
460
+ let outW = loaded.width;
461
+ let outH = loaded.height;
462
+ if (canCrop) {
463
+ const crop = computeGuideCropRect({
464
+ screenW: guide.screenW,
465
+ screenH: guide.screenH,
466
+ imageW: loaded.width,
467
+ imageH: loaded.height,
468
+ cutout: guide.cutout,
469
+ });
470
+ context.crop({
471
+ originX: crop.x,
472
+ originY: crop.y,
473
+ width: crop.width,
474
+ height: crop.height,
475
+ });
476
+ outW = crop.width;
477
+ outH = crop.height;
478
+ }
479
+
480
+ const longEdge = Math.max(outW, outH);
481
+ if (longEdge > MAX_LONG_EDGE) {
482
+ context.resize(
483
+ outW >= outH ? { width: MAX_LONG_EDGE } : { height: MAX_LONG_EDGE },
484
+ );
485
+ }
486
+
487
+ const rendered = await context.renderAsync();
488
+ try {
489
+ const result = await rendered.saveAsync({
490
+ compress: COMPRESS_QUALITY,
491
+ format: SaveFormat.JPEG,
492
+ });
493
+ const byteLength = await fetchByteLength(result.uri);
494
+ return {
495
+ uri: result.uri,
496
+ width: result.width,
497
+ height: result.height,
498
+ byteLength,
499
+ };
500
+ } finally {
501
+ rendered.release();
502
+ }
503
+ } finally {
504
+ context.release();
505
+ loaded.release();
506
+ loadContext.release();
507
+ }
389
508
  }
390
509
 
391
510
  async function uploadJpeg(uri: string, signedUrl: string): Promise<void> {
@@ -411,6 +530,25 @@ async function fetchByteLength(uri: string): Promise<number> {
411
530
  return blob.size;
412
531
  }
413
532
 
533
+ /**
534
+ * Fit a `width/height` box of the given aspect ratio inside `boxW × boxH`
535
+ * (contain). Returns the largest size that keeps the aspect ratio and fits —
536
+ * so the framed preview hugs the capture with no empty bands.
537
+ */
538
+ function fitContain(
539
+ aspect: number,
540
+ boxW: number,
541
+ boxH: number,
542
+ ): { width: number; height: number } {
543
+ let width = boxW;
544
+ let height = boxW / aspect;
545
+ if (height > boxH) {
546
+ height = boxH;
547
+ width = boxH * aspect;
548
+ }
549
+ return { width, height };
550
+ }
551
+
414
552
  function normalizeFileUri(uri: string): string {
415
553
  // Vision-camera returns paths with a leading `/var/mobile/...` on iOS
416
554
  // (no scheme) — `expo-image-manipulator` requires a `file://` prefix.
@@ -467,6 +605,16 @@ const styles = StyleSheet.create({
467
605
  alignItems: 'center',
468
606
  justifyContent: 'center',
469
607
  },
608
+ previewCard: {
609
+ borderWidth: 1,
610
+ overflow: 'hidden',
611
+ // Subtle lift so the framed capture reads as a deliberate card.
612
+ shadowColor: '#000',
613
+ shadowOpacity: 0.12,
614
+ shadowRadius: 10,
615
+ shadowOffset: { width: 0, height: 4 },
616
+ elevation: 3,
617
+ },
470
618
  preview: {
471
619
  width: '100%',
472
620
  height: '100%',