@myazahq/kyc-sdk-react-native 2.0.0

package/src/__tests__/errors.test.ts

@@ -0,0 +1,34 @@
+import { KYCApiError } from '../services/api';
+import { mapToKycError } from '../services/errors';
+
+describe('mapToKycError', () => {
+  it('maps 401 → invalid_api_key', () => {
+    const e = mapToKycError(new KYCApiError('nope', 401), 'verify');
+    expect(e.code).toBe('invalid_api_key');
+  });
+
+  it('maps 402 → insufficient_credits with details', () => {
+    const e = mapToKycError(new KYCApiError('no credits', 402, undefined, { required: 5, balance: 1, currency: 'USD' }), 'verify');
+    expect(e.code).toBe('insufficient_credits');
+    expect(e.details).toEqual({ required: 5, balance: 1, currency: 'USD' });
+  });
+
+  it('maps 403 id_type_not_allowed and feature_disabled → feature_disabled', () => {
+    expect(mapToKycError(new KYCApiError('x', 403, 'id_type_not_allowed'), 'verify').code).toBe('feature_disabled');
+    expect(mapToKycError(new KYCApiError('x', 403, 'feature_disabled', { feature: 'gov_db_check' }), 'verify').code).toBe('feature_disabled');
+  });
+
+  it('maps 5xx by context (upload_failed vs network_error)', () => {
+    expect(mapToKycError(new KYCApiError('x', 503), 'upload').code).toBe('upload_failed');
+    expect(mapToKycError(new KYCApiError('x', 503), 'verify').code).toBe('network_error');
+  });
+
+  it('maps a network TypeError → network_error', () => {
+    expect(mapToKycError(new TypeError('Network request failed'), 'verify').code).toBe('network_error');
+  });
+
+  it('falls back to the context code for unknown errors', () => {
+    expect(mapToKycError(new Error('weird'), 'upload').code).toBe('upload_failed');
+    expect(mapToKycError(new Error('weird'), 'verify').code).toBe('unknown');
+  });
+});

package/src/__tests__/flow.test.ts

@@ -0,0 +1,61 @@
+import { nextStepAfter, previousStepBefore, livenessEnabled, type KycState } from '../store/kycStore';
+import { INITIAL_SERVER_CONFIG } from '../store/serverConfig';
+import type { MyazaKYCConfig } from '../types/config';
+
+// Build a minimal KycState for exercising the pure navigation helpers. The
+// helpers only read currentStep/selectedIdType/serverConfig/config, so we cast a
+// partial object (the unused action fields are never touched).
+function makeState(over: Partial<KycState>): KycState {
+  const config = { apiKey: 'pk_test_x', country: 'NG', ...(over.config ?? {}) } as MyazaKYCConfig;
+  return {
+    config,
+    selectedIdType: null,
+    serverConfig: INITIAL_SERVER_CONFIG,
+    currentStep: 'consent',
+    ...over,
+  } as KycState;
+}
+
+describe('flow navigation', () => {
+  it('number-only IDs skip document capture (id-type → id-input)', () => {
+    const s = makeState({ selectedIdType: 'bvn' });
+    expect(nextStepAfter('id-type', s)).toBe('id-input');
+  });
+
+  it('document IDs go to document capture (id-type → document-capture)', () => {
+    const s = makeState({ selectedIdType: 'passport' });
+    expect(nextStepAfter('id-type', s)).toBe('document-capture');
+  });
+
+  it('reaches liveness when enabled, else jumps to submitted', () => {
+    const enabled = makeState({ selectedIdType: 'bvn', config: { apiKey: 'pk_test_x', country: 'NG', enableLiveness: true } as MyazaKYCConfig });
+    expect(nextStepAfter('id-input', enabled)).toBe('liveness');
+
+    const disabled = makeState({ selectedIdType: 'bvn', config: { apiKey: 'pk_test_x', country: 'NG', enableLiveness: false } as MyazaKYCConfig });
+    expect(nextStepAfter('id-input', disabled)).toBe('submitted');
+    expect(livenessEnabled(disabled)).toBe(false);
+  });
+
+  it('server livenessCheck=false wins over the consumer baseline', () => {
+    const s = makeState({
+      selectedIdType: 'bvn',
+      config: { apiKey: 'pk_test_x', country: 'NG', enableLiveness: true } as MyazaKYCConfig,
+      serverConfig: {
+        status: 'ready',
+        fatal: false,
+        idTypes: [{ country: 'NG', idType: 'bvn', features: { documentVerification: true, livenessCheck: false, govDbCheck: true } }],
+      },
+    });
+    expect(livenessEnabled(s)).toBe(false);
+    expect(nextStepAfter('id-input', s)).toBe('submitted');
+  });
+
+  it('back navigation mirrors the forward path', () => {
+    const doc = makeState({ selectedIdType: 'passport' });
+    expect(previousStepBefore('document-capture', doc)).toBe('id-type');
+    expect(previousStepBefore('liveness', doc)).toBe('document-capture');
+
+    const num = makeState({ selectedIdType: 'bvn' });
+    expect(previousStepBefore('liveness', num)).toBe('id-input');
+  });
+});

package/src/__tests__/gestureDetector.test.ts

@@ -0,0 +1,37 @@
+import { detectNod, detectTurn, detectBlink, detectSmile, pushHistory } from '../liveness/gestureDetector';
+
+describe('gesture detectors (native-signal thresholds, ported from Flutter)', () => {
+  it('detectNod passes when pitch dips below −10° then recovers above −5°', () => {
+    expect(detectNod([0, -12, -3])).toBe(true);
+    expect(detectNod([0, -6, -3])).toBe(false); // never dipped far enough
+    expect(detectNod([0, -12, -8])).toBe(false); // hasn't recovered
+    expect(detectNod([-12])).toBe(false); // <2 frames
+  });
+
+  it('detectTurn passes when yaw exceeds ±25°', () => {
+    expect(detectTurn(30)).toBe(true);
+    expect(detectTurn(-26)).toBe(true);
+    expect(detectTurn(20)).toBe(false);
+  });
+
+  it('detectBlink passes when eye-open drops below 0.2 then recovers above 0.5', () => {
+    expect(detectBlink([0.9, 0.1, 0.8])).toBe(true);
+    expect(detectBlink([0.9, 0.3, 0.8])).toBe(false); // never closed enough
+    expect(detectBlink([0.9, 0.1, 0.4])).toBe(false); // not recovered
+  });
+
+  it('detectSmile passes above 0.5', () => {
+    expect(detectSmile(0.6)).toBe(true);
+    expect(detectSmile(0.4)).toBe(false);
+  });
+});
+
+describe('pushHistory', () => {
+  it('appends and trims to maxLen', () => {
+    let h: number[] = [];
+    for (let i = 0; i < 25; i++) h = pushHistory(h, i, 20);
+    expect(h.length).toBe(20);
+    expect(h[h.length - 1]).toBe(24);
+    expect(h[0]).toBe(5);
+  });
+});

package/src/__tests__/liveness.test.ts

@@ -0,0 +1,112 @@
+// expo-speech is an ESM native module; the pure-logic tests here don't exercise
+// TTS, so stub it (matches jest.config's "native modules tested later" note).
+jest.mock('expo-speech', () => ({ speak: jest.fn(), stop: jest.fn() }));
+
+import { resolveVoiceGuidance } from '../liveness/speech';
+import { evaluateChallenge } from '../liveness/gestureDetector';
+import { pickChallenges, ChallengeTracker } from '../liveness/challengeManager';
+import type { LivenessFaceData } from '../liveness/types';
+
+// Pure-logic tests for the liveness machine's building blocks. The stateful hook
+// (useLiveness) and the native frame-processor bridge are exercised on-device;
+// here we lock down the ML-free pieces that drive them.
+
+function face(partial: Partial<LivenessFaceData> = {}): LivenessFaceData {
+  return {
+    headEulerAngleX: 0,
+    headEulerAngleY: 0,
+    headEulerAngleZ: 0,
+    smilingProbability: 0,
+    leftEyeOpenProbability: 1,
+    rightEyeOpenProbability: 1,
+    faceSizeRatio: 0.4,
+    faceCount: 1,
+    brightness: 128,
+    ...partial,
+  };
+}
+
+describe('resolveVoiceGuidance', () => {
+  it('treats undefined / true as enabled en-US', () => {
+    expect(resolveVoiceGuidance(undefined)).toEqual({ enabled: true, language: 'en-US' });
+    expect(resolveVoiceGuidance(true)).toEqual({ enabled: true, language: 'en-US' });
+  });
+
+  it('treats false as disabled', () => {
+    expect(resolveVoiceGuidance(false)).toEqual({ enabled: false, language: 'en-US' });
+  });
+
+  it('honours an object with enabled + language', () => {
+    expect(resolveVoiceGuidance({ enabled: true, language: 'fr-FR' })).toEqual({
+      enabled: true,
+      language: 'fr-FR',
+    });
+    // enabled defaults to true when omitted
+    expect(resolveVoiceGuidance({ language: 'en-GB' })).toEqual({ enabled: true, language: 'en-GB' });
+    expect(resolveVoiceGuidance({ enabled: false })).toEqual({ enabled: false, language: 'en-US' });
+  });
+});
+
+describe('evaluateChallenge (drives the state machine gesture switch)', () => {
+  it('nod reads the pitch history', () => {
+    expect(evaluateChallenge('nod', face(), [0, -12, -3], [])).toBe(true);
+    expect(evaluateChallenge('nod', face(), [0, -6], [])).toBe(false);
+  });
+
+  it('turn reads the latest yaw', () => {
+    expect(evaluateChallenge('turn', face({ headEulerAngleY: 30 }), [], [])).toBe(true);
+    expect(evaluateChallenge('turn', face({ headEulerAngleY: 10 }), [], [])).toBe(false);
+  });
+
+  it('blink reads the eye-open history', () => {
+    expect(evaluateChallenge('blink', face(), [], [0.9, 0.1, 0.8])).toBe(true);
+    expect(evaluateChallenge('blink', face(), [], [0.9, 0.3, 0.8])).toBe(false);
+  });
+
+  it('smile reads the latest smile probability', () => {
+    expect(evaluateChallenge('smile', face({ smilingProbability: 0.6 }), [], [])).toBe(true);
+    expect(evaluateChallenge('smile', face({ smilingProbability: 0.4 }), [], [])).toBe(false);
+  });
+});
+
+describe('pickChallenges (session selection)', () => {
+  it('picks the configured count of distinct challenges', () => {
+    const picked = pickChallenges({ challengeCount: 2 });
+    expect(picked).toHaveLength(2);
+    const types = picked.map((c) => c.type);
+    expect(new Set(types).size).toBe(2);
+  });
+
+  it('never pairs nod with turn (similarity group)', () => {
+    for (let i = 0; i < 50; i++) {
+      const types = pickChallenges({ challengeCount: 2 }).map((c) => c.type);
+      const hasNod = types.includes('nod');
+      const hasTurn = types.includes('turn');
+      expect(hasNod && hasTurn).toBe(false);
+    }
+  });
+
+  it('respects a restricted challengePool', () => {
+    const picked = pickChallenges({ challengeCount: 2, challengePool: ['blink', 'smile'] });
+    expect(picked.every((c) => c.type === 'blink' || c.type === 'smile')).toBe(true);
+  });
+
+  it('applies the per-challenge timeout override', () => {
+    const picked = pickChallenges({ challengeCount: 2, timeoutPerChallenge: 5 });
+    expect(picked.every((c) => c.timeoutSeconds === 5)).toBe(true);
+  });
+});
+
+describe('ChallengeTracker (progress)', () => {
+  it('advances through challenges and reports completion', () => {
+    const tracker = new ChallengeTracker(pickChallenges({ challengeCount: 2 }));
+    expect(tracker.totalCount).toBe(2);
+    expect(tracker.isComplete).toBe(false);
+
+    tracker.markCurrentPassed();
+    expect(tracker.advance()).toBe(true); // a second challenge exists
+    tracker.markCurrentPassed();
+    expect(tracker.advance()).toBe(false); // none left
+    expect(tracker.isComplete).toBe(true);
+  });
+});

package/src/__tests__/resolveUrl.test.ts

@@ -0,0 +1,64 @@
+import { detectEnvironment, resolveBaseUrl, normalizeDevAssetUrl } from '../services/resolveUrl';
+
+describe('detectEnvironment', () => {
+  it('maps each prefix (pk_ and sk_) to its environment', () => {
+    expect(detectEnvironment('pk_dev_abc')).toBe('development');
+    expect(detectEnvironment('sk_dev_abc')).toBe('development');
+    expect(detectEnvironment('pk_test_abc')).toBe('sandbox');
+    expect(detectEnvironment('sk_test_abc')).toBe('sandbox');
+    expect(detectEnvironment('pk_live_abc')).toBe('production');
+    expect(detectEnvironment('sk_live_abc')).toBe('production');
+  });
+
+  it('throws on an unrecognized / malformed key', () => {
+    expect(() => detectEnvironment('nope')).toThrow(/Invalid Myaza API key/);
+    expect(() => detectEnvironment('pk_prod_abc')).toThrow();
+    expect(() => detectEnvironment('')).toThrow();
+  });
+});
+
+describe('resolveBaseUrl', () => {
+  it('uses the hardcoded sandbox/production URLs and ignores devUrl', () => {
+    expect(resolveBaseUrl('pk_test_abc')).toBe('https://sandbox.identity.myaza.app');
+    expect(resolveBaseUrl('pk_test_abc', 'http://example.test')).toBe('https://sandbox.identity.myaza.app');
+    expect(resolveBaseUrl('pk_live_abc')).toBe('https://identity.myaza.app');
+  });
+
+  it('uses devUrl for development keys, defaulting to localhost', () => {
+    expect(resolveBaseUrl('pk_dev_abc', 'http://192.168.1.5:3001')).toBe('http://192.168.1.5:3001');
+    // Under the Node test runner Platform falls back to iOS → localhost.
+    expect(resolveBaseUrl('pk_dev_abc')).toBe('http://localhost:3001');
+  });
+});
+
+describe('normalizeDevAssetUrl', () => {
+  it('rewrites a localhost-family asset origin to the dev base origin', () => {
+    expect(normalizeDevAssetUrl('http://localhost:3001/api/kyc/branding/logo/x', 'http://10.0.2.2:3001')).toBe(
+      'http://10.0.2.2:3001/api/kyc/branding/logo/x',
+    );
+    expect(normalizeDevAssetUrl('http://127.0.0.1:3001/logo.png', 'http://10.0.2.2:3001')).toBe(
+      'http://10.0.2.2:3001/logo.png',
+    );
+  });
+
+  it('is a no-op when the base origin already matches', () => {
+    expect(normalizeDevAssetUrl('http://localhost:3001/logo.png', 'http://localhost:3001')).toBe(
+      'http://localhost:3001/logo.png',
+    );
+  });
+
+  it('never touches production/CDN URLs or an https base', () => {
+    // Public CDN asset, dev base → left alone (not a localhost host).
+    expect(normalizeDevAssetUrl('https://cdn.myaza.app/logo.png', 'http://10.0.2.2:3001')).toBe(
+      'https://cdn.myaza.app/logo.png',
+    );
+    // https base (sandbox/prod) → never rewrites, even a localhost asset.
+    expect(normalizeDevAssetUrl('http://localhost:3001/logo.png', 'https://sandbox.identity.myaza.app')).toBe(
+      'http://localhost:3001/logo.png',
+    );
+  });
+
+  it('passes through undefined', () => {
+    expect(normalizeDevAssetUrl(undefined, 'http://10.0.2.2:3001')).toBeUndefined();
+  });
+});

package/src/__tests__/validators.test.ts

@@ -0,0 +1,38 @@
+import { validateIdNumber, maskIdNumber } from '../services/validators';
+
+describe('validateIdNumber', () => {
+  it('validates Nigerian number-only IDs', () => {
+    expect(validateIdNumber('NG', 'bvn', '12345678901').valid).toBe(true);
+    expect(validateIdNumber('NG', 'bvn', '123').valid).toBe(false);
+    expect(validateIdNumber('NG', 'nin', '12345678901').valid).toBe(true);
+    expect(validateIdNumber('NG', 'vnin', 'ABCD123456789012').valid).toBe(true);
+    expect(validateIdNumber('NG', 'vnin', 'short').valid).toBe(false);
+  });
+
+  it('validates country-prefixed shared keys (passport, national-id)', () => {
+    expect(validateIdNumber('NG', 'passport', 'A12345678').valid).toBe(true);
+    expect(validateIdNumber('NG', 'passport', 'A1234567').valid).toBe(false); // GH format, not NG
+    expect(validateIdNumber('GH', 'passport', 'A1234567').valid).toBe(true);
+    expect(validateIdNumber('KE', 'national-id', '12345678').valid).toBe(true);
+    expect(validateIdNumber('ZA', 'national-id', '1234567890123').valid).toBe(true);
+  });
+
+  it('validates Ghana Card and PVC patterns', () => {
+    expect(validateIdNumber('GH', 'ghana-card', 'GHA-123456789-0').valid).toBe(true);
+    expect(validateIdNumber('GH', 'ghana-card', '123456789').valid).toBe(false);
+    expect(validateIdNumber('NG', 'pvc', '1234567890123456789').valid).toBe(true);
+  });
+
+  it('rejects empty input', () => {
+    expect(validateIdNumber('NG', 'bvn', '   ').valid).toBe(false);
+  });
+});
+
+describe('maskIdNumber', () => {
+  it('masks the middle of a long number', () => {
+    expect(maskIdNumber('12345678901')).toBe('1234****901');
+  });
+  it('leaves short values untouched', () => {
+    expect(maskIdNumber('1234567')).toBe('1234567');
+  });
+});

package/src/components/CameraPermissionView.tsx

@@ -0,0 +1,116 @@
+import React from 'react';
+import { Linking, Platform, View } from 'react-native';
+
+import { radius, spacing } from '../config/theme';
+import { useTheme } from './runtime';
+import { MyazaText } from './Typography';
+import { MyazaButton } from './MyazaButton';
+import { Icon, type IconName } from './Icon';
+
+// Camera error states for the document-capture step. Two variants share one
+// scaffold (an 80×80 error-tinted circle + heading + message + actions):
+//   • CameraPermissionView   — OS permission denied ("Camera access needed")
+//                              → Open Settings + Try Again (Android only) + Upload
+//   • CameraUnavailableView  — no camera device / init failure ("Camera not available")
+//                              → Upload a photo instead
+// Both mirror the Flutter SDK's permission/error treatment.
+
+interface ScaffoldProps {
+  icon: IconName;
+  title: string;
+  message: string;
+  /** When true (default), vertically centers; false flows top-down below a heading. */
+  centered?: boolean;
+  children: React.ReactNode; // action buttons
+}
+
+function CameraErrorScaffold({ icon, title, message, centered = true, children }: ScaffoldProps): React.ReactElement {
+  const { colors } = useTheme();
+  return (
+    <View
+      style={
+        centered
+          ? { flex: 1, alignItems: 'center', justifyContent: 'center', paddingVertical: spacing.xl }
+          : { alignItems: 'center', paddingTop: spacing.lg, paddingBottom: spacing.xl }
+      }
+    >
+      <View
+        style={{
+          width: 80,
+          height: 80,
+          borderRadius: radius.full,
+          backgroundColor: `${colors.error}1A`,
+          alignItems: 'center',
+          justifyContent: 'center',
+        }}
+      >
+        <Icon name={icon} size={38} color={colors.error} />
+      </View>
+      <View style={{ height: spacing.lg }} />
+      <MyazaText variant="heading2" style={{ textAlign: 'center' }}>
+        {title}
+      </MyazaText>
+      <View style={{ height: spacing.xs }} />
+      <MyazaText variant="bodyMedium" color={colors.textSecondary} style={{ textAlign: 'center' }}>
+        {message}
+      </MyazaText>
+      <View style={{ height: spacing.lg }} />
+      <View style={{ width: '100%' }}>{children}</View>
+    </View>
+  );
+}
+
+// ── Permission denied ────────────────────────────────────────────────────────
+
+const DEFAULT_PERMISSION_MESSAGE =
+  'Camera access is required to photograph your document. Please allow camera access, or upload a photo instead.';
+
+export interface CameraPermissionViewProps {
+  message?: string;
+  onRetry: () => void;
+  /** Secondary action — e.g. "Upload a photo instead" on document capture. */
+  onUpload?: () => void;
+  centered?: boolean;
+}
+
+export function CameraPermissionView({ message, onRetry, onUpload, centered = true }: CameraPermissionViewProps): React.ReactElement {
+  // iOS: re-checking in place can't succeed (only Settings grants, which
+  // relaunches the app), so omit "Try Again" there — matches Flutter.
+  const showRetry = Platform.OS !== 'ios';
+  return (
+    <CameraErrorScaffold icon="camera-off" title="Camera access needed" message={message ?? DEFAULT_PERMISSION_MESSAGE} centered={centered}>
+      <MyazaButton label="Open Settings" onPress={() => void Linking.openSettings()} />
+      {showRetry ? (
+        <>
+          <View style={{ height: spacing.sm }} />
+          <MyazaButton label="Try Again" variant="outline" onPress={onRetry} />
+        </>
+      ) : null}
+      {onUpload ? (
+        <>
+          <View style={{ height: spacing.sm }} />
+          <MyazaButton label="Upload a photo instead" variant="ghost" leadingIcon="upload" onPress={onUpload} />
+        </>
+      ) : null}
+    </CameraErrorScaffold>
+  );
+}
+
+// ── Camera unavailable (no device / init failure) ────────────────────────────
+
+const DEFAULT_UNAVAILABLE_MESSAGE =
+  "We couldn't start the camera on this device. Please upload a photo of your document instead.";
+
+export interface CameraUnavailableViewProps {
+  message?: string;
+  onUpload?: () => void;
+  centered?: boolean;
+}
+
+export function CameraUnavailableView({ message, onUpload, centered = true }: CameraUnavailableViewProps): React.ReactElement {
+  return (
+    <CameraErrorScaffold icon="video-off" title="Camera not available" message={message ?? DEFAULT_UNAVAILABLE_MESSAGE} centered={centered}>
+      {onUpload ? <MyazaButton label="Upload a photo instead" leadingIcon="upload" onPress={onUpload} /> : null}
+    </CameraErrorScaffold>
+  );
+}

package/src/components/CameraViewfinder.tsx

@@ -0,0 +1,156 @@
+import React, { useEffect } from 'react';
+import { ActivityIndicator, Pressable, View } from 'react-native';
+import Svg, { Defs, Mask, Path, Rect } from 'react-native-svg';
+import { Camera, useCameraDevice, usePhotoOutput, useVideoOutput } from 'react-native-vision-camera';
+
+import { radius, spacing } from '../config/theme';
+import { DOCUMENT_VIDEO_BITRATE, VIDEO_CAPTURE_RESOLUTION } from '../config/captureSettings';
+import { useTheme } from './runtime';
+import { useVideoRecorder } from './useVideoRecorder';
+import { MyazaText } from './Typography';
+import { Icon } from './Icon';
+
+// Back-camera viewfinder for document capture — the RN mirror of the Flutter
+// SDK's _DocumentViewfinder. Shows a VisionCamera preview with an ID-card guide
+// overlay + manual shutter. This component is only rendered once a camera device
+// exists (or while it's still resolving — a brief spinner); the "Camera not
+// available" error (no device / init failure) is owned by the parent step, which
+// shows a prominent error + upload fallback. Capture is manual (no edge detection).
+
+// Card window within the 3:4 viewBox (centred). Height follows the per-ID guide
+// aspect so the overlay matches the auto-crop (cropCardRegion).
+const VB_W = 100;
+const VB_H = 133;
+const GX = 6;
+const GW = 88;
+const C = 7; // corner accent length
+
+export interface CameraViewfinderProps {
+  active: boolean;
+  side: 'front' | 'back';
+  documentLabel: string;
+  /** Receives the captured still + a best-effort short document video (or null). */
+  onCapture: (uri: string, videoPath: string | null) => void;
+  /** Card-guide aspect (width ÷ height): 1.586 for ID cards, 1.42 for passports. */
+  guideAspect?: number;
+  /** Capture is disabled while a previous capture/compress is in flight. */
+  busy?: boolean;
+}
+
+export function CameraViewfinder({
+  active,
+  side,
+  documentLabel,
+  onCapture,
+  guideAspect = 1.586,
+  busy = false,
+}: CameraViewfinderProps): React.ReactElement {
+  const { colors } = useTheme();
+  const device = useCameraDevice('back');
+  // v5: document-conservative still (OCR). Capture via the photo output, not a
+  // camera ref. Quality is prioritised so small text stays legible.
+  const photoOutput = usePhotoOutput({ qualityPrioritization: 'quality' });
+  // A short, bitrate-capped document video recorded alongside the still (uploaded
+  // best-effort as document_front_video / document_back_video). Mirrors Flutter.
+  const videoOutput = useVideoOutput({
+    enableAudio: false,
+    fileType: 'mp4',
+    targetBitRate: DOCUMENT_VIDEO_BITRATE,
+    targetResolution: VIDEO_CAPTURE_RESOLUTION,
+    // iOS only honours targetBitRate/targetResolution on the AVAssetWriter
+    // pipeline; without this it records full-quality (the front clip exceeded the
+    // 25MB upload cap). This keeps the document video small.
+    enablePersistentRecorder: true,
+  });
+  const ready = !!device;
+  const recorder = useVideoRecorder(videoOutput, ready);
+
+  // Record while the side's camera is live; restart when the side changes.
+  useEffect(() => {
+    if (active && ready) recorder.start();
+    return () => {
+      void recorder.stop();
+    };
+    // `side` in the deps restarts the recording for the back side.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [active, ready, side]);
+
+  const GH = GW / guideAspect;
+  const GY = (VB_H - GH) / 2;
+
+  const capture = async () => {
+    if (busy || !ready) return;
+    try {
+      // Stop the video first (and grab its path) so the still and the clip don't
+      // contend for the camera, then capture the OCR still.
+      const videoPath = await recorder.stop();
+      const file = await photoOutput.capturePhotoToFile({ flashMode: 'off' }, {});
+      onCapture(`file://${file.filePath}`, videoPath);
+    } catch {
+      /* a failed shutter is a no-op — the user can tap again */
+    }
+  };
+
+  return (
+    <View style={{ width: '100%', aspectRatio: 3 / 4, borderRadius: radius.lg, overflow: 'hidden', backgroundColor: '#111111' }}>
+      {ready ? (
+        <Camera style={{ flex: 1 }} device={device} isActive={active} outputs={[photoOutput, videoOutput]} />
+      ) : (
+        <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
+          <ActivityIndicator color="#FFFFFF" />
+        </View>
+      )}
+
+      {/* Card-guide overlay (only over a live preview) */}
+      {ready ? (
+        <>
+          <Svg style={{ position: 'absolute', inset: 0 }} viewBox={`0 0 ${VB_W} ${VB_H}`} preserveAspectRatio="none">
+            <Defs>
+              <Mask id="cardMask">
+                <Rect width={VB_W} height={VB_H} fill="white" />
+                <Rect x={GX} y={GY} width={GW} height={GH} rx={3} fill="black" />
+              </Mask>
+            </Defs>
+            <Rect width={VB_W} height={VB_H} fill="rgba(0,0,0,0.55)" mask="url(#cardMask)" />
+            <Rect x={GX} y={GY} width={GW} height={GH} rx={3} fill="none" stroke="rgba(255,255,255,0.85)" strokeWidth={0.6} strokeDasharray="5 3" />
+            <Path d={`M${GX},${GY + C} L${GX},${GY} L${GX + C},${GY}`} stroke={colors.primary} strokeWidth={1.6} fill="none" strokeLinecap="round" />
+            <Path d={`M${GX + GW - C},${GY} L${GX + GW},${GY} L${GX + GW},${GY + C}`} stroke={colors.primary} strokeWidth={1.6} fill="none" strokeLinecap="round" />
+            <Path d={`M${GX + GW},${GY + GH - C} L${GX + GW},${GY + GH} L${GX + GW - C},${GY + GH}`} stroke={colors.primary} strokeWidth={1.6} fill="none" strokeLinecap="round" />
+            <Path d={`M${GX + C},${GY + GH} L${GX},${GY + GH} L${GX},${GY + GH - C}`} stroke={colors.primary} strokeWidth={1.6} fill="none" strokeLinecap="round" />
+          </Svg>
+          <View style={{ position: 'absolute', top: spacing.md, left: 0, right: 0, alignItems: 'center' }}>
+            <View style={{ backgroundColor: 'rgba(0,0,0,0.4)', paddingHorizontal: spacing.sm + 4, paddingVertical: 6, borderRadius: radius.full }}>
+              <MyazaText variant="bodySmall" color="#FFFFFF">
+                {`Align the ${side === 'back' ? 'BACK' : 'FRONT'} of your ${documentLabel}`}
+              </MyazaText>
+            </View>
+          </View>
+        </>
+      ) : null}
+
+      {/* Shutter — disabled when the camera isn't ready */}
+      <View style={{ position: 'absolute', bottom: spacing.lg, left: 0, right: 0, alignItems: 'center' }}>
+        <Pressable
+          onPress={capture}
+          disabled={busy || !ready}
+          accessibilityRole="button"
+          accessibilityLabel="Capture photo"
+          style={({ pressed }) => ({
+            width: 64,
+            height: 64,
+            borderRadius: radius.full,
+            backgroundColor: ready ? '#FFFFFF' : colors.gray400,
+            borderWidth: 4,
+            borderColor: ready ? colors.primary : colors.gray300,
+            alignItems: 'center',
+            justifyContent: 'center',
+            opacity: busy ? 0.6 : 1,
+            transform: [{ scale: pressed ? 0.94 : 1 }],
+          })}
+        >
+          {busy ? <ActivityIndicator color={colors.primary} /> : <Icon name="camera" size={24} color={ready ? colors.primary : '#FFFFFF'} />}
+        </Pressable>
+      </View>
+    </View>
+  );
+}