@myazahq/kyc-sdk-react-native 2.0.0

package/src/components/toast.tsx

@@ -0,0 +1,154 @@
+import React, { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react';
+import { Animated, Easing, Platform, Pressable, StatusBar, View } from 'react-native';
+import { initialWindowMetrics } from 'react-native-safe-area-context';
+
+import { radius, spacing } from '../config/theme';
+import { useTheme } from './runtime';
+import { MyazaText } from './Typography';
+import { Icon } from './Icon';
+
+// Top toast — the RN SDK surfaces technical errors (upload/network failures) as a
+// toast that slides down from the top of the modal, rather than an inline alert.
+// Mounted once (by KycFlow) so any step can raise one via `useToast()`.
+
+type ToastVariant = 'error' | 'success' | 'warning' | 'info';
+
+export interface ToastInput {
+  message: string;
+  title?: string;
+  variant?: ToastVariant;
+  /** Auto-dismiss after this many ms (0 = sticky). Default 4500. */
+  duration?: number;
+}
+
+interface ToastApi {
+  show: (toast: ToastInput) => void;
+  hide: () => void;
+}
+
+const ToastContext = createContext<ToastApi>({ show: () => {}, hide: () => {} });
+
+/** Raise/dismiss the top toast. No-op outside the SDK modal. */
+export function useToast(): ToastApi {
+  return useContext(ToastContext);
+}
+
+export function ToastProvider({ children }: { children: React.ReactNode }): React.ReactElement {
+  const [toast, setToast] = useState<(ToastInput & { id: number }) | null>(null);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const idRef = useRef(0);
+
+  const hide = useCallback(() => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+    timerRef.current = null;
+    setToast(null);
+  }, []);
+
+  const show = useCallback((input: ToastInput) => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+    idRef.current += 1;
+    setToast({ ...input, id: idRef.current });
+    const dur = input.duration ?? 4500;
+    if (dur > 0) {
+      timerRef.current = setTimeout(() => setToast(null), dur);
+    }
+  }, []);
+
+  useEffect(() => () => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+  }, []);
+
+  return (
+    <ToastContext.Provider value={{ show, hide }}>
+      <View style={{ flex: 1 }}>
+        {children}
+        {toast ? <ToastView key={toast.id} {...toast} onDismiss={hide} /> : null}
+      </View>
+    </ToastContext.Provider>
+  );
+}
+
+function ToastView({
+  message,
+  title,
+  variant = 'error',
+  onDismiss,
+}: ToastInput & { onDismiss: () => void }): React.ReactElement {
+  const { colors } = useTheme();
+  const anim = useRef(new Animated.Value(0)).current;
+
+  useEffect(() => {
+    Animated.timing(anim, {
+      toValue: 1,
+      duration: 250,
+      easing: Easing.out(Easing.cubic),
+      useNativeDriver: true,
+    }).start();
+  }, [anim]);
+
+  // Slide in below the status bar / notch.
+  const topInset =
+    (initialWindowMetrics?.insets.top ?? (Platform.OS === 'android' ? StatusBar.currentHeight ?? 0 : 0)) +
+    spacing.sm;
+
+  const accent =
+    variant === 'success'
+      ? colors.success
+      : variant === 'warning'
+        ? colors.warning
+        : variant === 'info'
+          ? colors.primary
+          : colors.error;
+  const iconName = variant === 'success' ? 'check' : 'alert';
+
+  return (
+    <Animated.View
+      pointerEvents="box-none"
+      style={{
+        position: 'absolute',
+        top: topInset,
+        left: spacing.md,
+        right: spacing.md,
+        opacity: anim,
+        transform: [{ translateY: anim.interpolate({ inputRange: [0, 1], outputRange: [-24, 0] }) }],
+      }}
+    >
+      <View
+        style={{
+          flexDirection: 'row',
+          alignItems: 'flex-start',
+          gap: spacing.sm,
+          backgroundColor: colors.background,
+          borderRadius: radius.md,
+          borderLeftWidth: 3,
+          borderLeftColor: accent,
+          paddingHorizontal: spacing.md,
+          paddingVertical: spacing.sm + 2,
+          // Subtle elevation so it reads as floating above the content.
+          shadowColor: '#000000',
+          shadowOpacity: 0.18,
+          shadowRadius: 12,
+          shadowOffset: { width: 0, height: 4 },
+          elevation: 6,
+          borderWidth: 1,
+          borderColor: colors.border,
+        }}
+      >
+        <Icon name={iconName} size={18} color={accent} />
+        <View style={{ flex: 1 }}>
+          {title ? (
+            <MyazaText variant="bodySmall" color={accent} style={{ fontWeight: '700' }}>
+              {title}
+            </MyazaText>
+          ) : null}
+          <MyazaText variant="bodySmall" color={colors.textDark}>
+            {message}
+          </MyazaText>
+        </View>
+        <Pressable onPress={onDismiss} hitSlop={8} accessibilityRole="button" accessibilityLabel="Dismiss">
+          <Icon name="close" size={16} color={colors.textMuted} />
+        </Pressable>
+      </View>
+    </Animated.View>
+  );
+}

package/src/components/useBranding.ts

@@ -0,0 +1,27 @@
+import { useKyc, useKycConfig } from './runtime';
+
+// Resolves the org logo + company name shown in the persistent header brand.
+// Mirrors the web SDK's `useBranding` and the Flutter logo-resolution logic:
+//   appearance.logo === 'default' → serverConfig.branding.logo (config endpoint)
+//   any other value               → literal image URL
+// The header brand is gated on a logo being present (no logo → no company name).
+
+export interface ResolvedBranding {
+  logoUri: string | null;
+  companyName: string;
+}
+
+export function useBranding(): ResolvedBranding {
+  const config = useKycConfig();
+  const branding = useKyc((s) => s.serverConfig.branding);
+
+  const appearanceLogo = config.appearance?.logo;
+  const logoUri =
+    appearanceLogo === 'default'
+      ? branding?.logo ?? null
+      : appearanceLogo ?? null;
+
+  const companyName = config.appearance?.companyName ?? branding?.companyName ?? 'Myaza';
+
+  return { logoUri, companyName };
+}

package/src/components/useVideoRecorder.ts

@@ -0,0 +1,122 @@
+import { useCallback, useRef } from 'react';
+import type { CameraVideoOutput, Recorder } from 'react-native-vision-camera';
+
+import { MAX_VIDEO_DURATION_MS } from '../config/captureSettings';
+
+// Shared best-effort video recorder for the VisionCamera v5 output model, used by
+// both the liveness selfie video and the document-capture videos. Mirrors the
+// Flutter SDK's "record while the camera is live, stop when the still is taken,
+// upload best-effort" pattern.
+//
+// Three robustness concerns are handled here:
+//  • The video output connects to the camera session a moment after mount, so the
+//    first start can throw "VideoOutput is not yet connected" — we retry briefly.
+//  • The finished file path arrives via the `onRecordingFinished` callback (not the
+//    stopRecording promise), so we bridge the two and bound the wait.
+//  • A hard duration cap (MAX_VIDEO_DURATION_MS) auto-stops the recording so a long
+//    camera session can't bloat the file past the upload ceiling.
+
+export interface VideoRecorderHandle {
+  /** Start recording (no-op if disabled or already recording). */
+  start: () => void;
+  /** Stop and resolve the recorded `file://` path, or null if nothing recorded. */
+  stop: () => Promise<string | null>;
+  /** True while a recording is in progress. */
+  isRecording: () => boolean;
+}
+
+export function useVideoRecorder(videoOutput: CameraVideoOutput, enabled: boolean): VideoRecorderHandle {
+  const recordingRef = useRef(false);
+  const recorderRef = useRef<Recorder | null>(null);
+  const pathRef = useRef<string | null>(null);
+  const finishedRef = useRef<Promise<string | null> | null>(null);
+  const resolveFinishedRef = useRef<((p: string | null) => void) | null>(null);
+  const stoppingRef = useRef(false);
+  const autoStopRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const start = useCallback(() => {
+    if (recordingRef.current || !enabled) return;
+    recordingRef.current = true;
+    stoppingRef.current = false;
+    pathRef.current = null;
+    finishedRef.current = new Promise<string | null>((resolve) => {
+      resolveFinishedRef.current = resolve;
+    });
+    void (async () => {
+      const onFinished = (filePath: string) => {
+        pathRef.current = `file://${filePath}`;
+        resolveFinishedRef.current?.(pathRef.current);
+        resolveFinishedRef.current = null;
+      };
+      const onError = () => {
+        recordingRef.current = false;
+        recorderRef.current = null;
+        resolveFinishedRef.current?.(null);
+        resolveFinishedRef.current = null;
+      };
+      // Retry until the video output is connected to the session (~2.4s); the
+      // "not yet connected" error is transient. Any other error → bail (best-effort).
+      for (let attempt = 0; attempt < 12; attempt++) {
+        if (!recordingRef.current) return; // stopped before it ever started
+        try {
+          const recorder = await videoOutput.createRecorder({});
+          await recorder.startRecording(onFinished, onError);
+          recorderRef.current = recorder;
+          // Hard length cap — stop the recording (path arrives via onFinished); a
+          // later stop() will just await the already-resolved path.
+          autoStopRef.current = setTimeout(() => {
+            if (recorderRef.current && !stoppingRef.current) {
+              stoppingRef.current = true;
+              void recorderRef.current.stopRecording().catch(() => {});
+            }
+          }, MAX_VIDEO_DURATION_MS);
+          return; // recording is live
+        } catch (e) {
+          const msg = String(e);
+          if (msg.includes('not yet connected') || msg.includes('CameraSession')) {
+            await new Promise((r) => setTimeout(r, 200));
+            continue;
+          }
+          break;
+        }
+      }
+      recordingRef.current = false;
+      recorderRef.current = null;
+      resolveFinishedRef.current?.(null);
+      resolveFinishedRef.current = null;
+    })();
+  }, [videoOutput, enabled]);
+
+  const stop = useCallback(async (): Promise<string | null> => {
+    if (autoStopRef.current) {
+      clearTimeout(autoStopRef.current);
+      autoStopRef.current = null;
+    }
+    if (!recordingRef.current) return pathRef.current;
+    if (!recorderRef.current) {
+      // Still in the start-retry loop (output not connected yet) — cancel it.
+      recordingRef.current = false;
+      return pathRef.current;
+    }
+    if (!stoppingRef.current) {
+      stoppingRef.current = true;
+      try {
+        await recorderRef.current.stopRecording();
+      } catch {
+        /* already stopping / not started — fall through to the path wait */
+      }
+    }
+    // The final path arrives via onRecordingFinished; bound the wait (~2s).
+    const path = await Promise.race([
+      finishedRef.current ?? Promise.resolve(pathRef.current),
+      new Promise<string | null>((resolve) => setTimeout(() => resolve(pathRef.current), 2000)),
+    ]);
+    recordingRef.current = false;
+    recorderRef.current = null;
+    return path;
+  }, []);
+
+  const isRecording = useCallback(() => recordingRef.current, []);
+
+  return { start, stop, isRecording };
+}

package/src/config/captureSettings.ts

@@ -0,0 +1,67 @@
+// ===========================================================================
+// Capture & encoding settings — compression strategy
+// ===========================================================================
+//
+// Mirrors the web SDK's `lib/capture-settings.ts` and the Flutter SDK's
+// `CaptureConfig`. Effort is scaled to how much quality each artifact needs:
+//
+//   • VIDEO (liveness + document)  — AGGRESSIVE: low res + low frame rate +
+//       a ~500 kbps bitrate cap. A few seconds stays well under the size target.
+//   • SELFIE still image           — MODERATE: 640×480, JPEG quality 0.8.
+//   • DOCUMENT still image         — CONSERVATIVE (OCR-critical): captured at a
+//       higher resolution, JPEG quality 0.9, never downscaled below 1080 px.
+// ===========================================================================
+
+// --- Liveness / selfie camera (video is recorded from this stream) ---------
+export const CAPTURE_WIDTH = 640;
+export const CAPTURE_HEIGHT = 480;
+
+// --- Document camera (higher res so the OCR still stays readable) ----------
+export const DOCUMENT_CAPTURE_WIDTH = 1920;
+export const DOCUMENT_CAPTURE_HEIGHT = 1080;
+
+// --- Frame rate (applies to every recorded stream) -------------------------
+export const CAPTURE_FRAMERATE = 15;
+export const CAPTURE_FRAMERATE_MAX = 20;
+
+// --- Video size strategy (liveness + document) -----------------------------
+// These videos are EVIDENCE ONLY — they're not compared against anything and may
+// never be looked at, so we optimise purely for small file size (low res + low
+// frame rate + low bitrate). Every clip must stay under MAX_VIDEO_BYTES (5 MB);
+// the recorder also stops at MAX_VIDEO_DURATION_MS and the uploader skips anything
+// still over the cap, so a video can never exceed 5 MB regardless of how long the
+// user lingers on the camera.
+export const LIVENESS_VIDEO_BITRATE = 350_000; // 350 kbps
+export const DOCUMENT_VIDEO_BITRATE = 350_000; // 350 kbps
+
+/** Recorded video resolution — small (360p-ish). Quality is irrelevant here. */
+export const VIDEO_CAPTURE_RESOLUTION = { width: 360, height: 640 } as const;
+
+// NOTE: VisionCamera v5 does NOT honour targetBitRate / targetResolution for
+// recordings on iOS — the whole session uses ONE camera format, driven by the
+// document photo output's `quality` prioritisation (4K, for OCR), so the raw clip
+// is huge (a 6s capture was ~35 MB). We therefore TRANSCODE every recorded clip
+// down with react-native-compressor before upload (see services/mediaCompress
+// `compressVideo`) — the real file-size lever. The raw recording is duration-capped
+// only to bound the temp file we hand to the transcoder.
+export const MAX_VIDEO_DURATION_MS = 12_000; // bounds the raw 4K temp file
+
+/** Transcode target — longest edge (≈480p) and bitrate for the uploaded clip. */
+export const VIDEO_COMPRESS_MAX_SIZE = 640;
+export const VIDEO_COMPRESS_BITRATE = 600_000; // 600 kbps → 12s ≈ 0.9 MB
+
+/** Hard upload ceiling — any video still over this (transcode failed) is dropped. */
+export const MAX_VIDEO_BYTES = 5 * 1024 * 1024; // 5 MB
+
+/** Pause before the liveness selfie shutter so the user steadies after the final
+ *  gesture (a head turn leaves them mid-motion) → a sharper, non-blurred selfie. */
+export const SELFIE_SETTLE_MS = 1500;
+
+// --- Still-image JPEG quality (0–1) ----------------------------------------
+export const SELFIE_IMAGE_QUALITY = 0.8; // moderate
+export const DOCUMENT_IMAGE_QUALITY = 0.9; // conservative — keep text sharp
+
+/** Document stills are never scaled narrower than this (OCR-critical). */
+export const DOCUMENT_MIN_WIDTH = 1080;
+/** Upper bound for document stills — large enough to keep small text legible. */
+export const DOCUMENT_MAX_DIMENSION = 2000;

package/src/config/idTypes.ts

@@ -0,0 +1,79 @@
+import type { IdTypesByCountry } from '../types/config';
+
+/**
+ * Source of truth for the supported `(country, idType)` matrix — identical to
+ * the web SDK's `utils/countries.ts` and the Flutter SDK's `id_types.dart`.
+ * `requiresDocumentCapture: false` ⇒ number-only path (no document scan).
+ */
+export const ID_TYPES: IdTypesByCountry = {
+  NG: [
+    { key: 'bvn',             label: 'BVN',                            digits: 11,                    requiresDocumentCapture: false },
+    { key: 'nin',             label: 'NIN',                            digits: 11,                    requiresDocumentCapture: false },
+    { key: 'vnin',            label: 'Virtual NIN (vNIN)',             digits: 16,                    requiresDocumentCapture: false },
+    { key: 'passport',        label: 'International Passport',          pattern: /^[A-Z]\d{8}$/,       requiresDocumentCapture: true, scanSides: 'front_only'     },
+    { key: 'drivers-license', label: "Driver's License",               pattern: /^[A-Z]{3}\d{5,12}$/, requiresDocumentCapture: true, scanSides: 'front_and_back' },
+    { key: 'pvc',             label: "Permanent Voter's Card",         pattern: /^\d{19}$/,           requiresDocumentCapture: true, scanSides: 'front_and_back' },
+  ],
+  GH: [
+    { key: 'ghana-card',      label: 'Ghana Card',                     pattern: /^GHA-\d{9}-\d$/,     requiresDocumentCapture: true, scanSides: 'front_and_back' },
+    { key: 'voters',          label: "Voter's Card",                   digits: 10,                    requiresDocumentCapture: true, scanSides: 'front_and_back' },
+    { key: 'drivers-license', label: "Driver's License",                                              requiresDocumentCapture: true, scanSides: 'front_and_back' },
+    { key: 'ssnit',           label: 'SSNIT',                          digits: 13,                    requiresDocumentCapture: true, scanSides: 'front_only'     },
+    { key: 'passport',        label: 'Passport',                       pattern: /^[A-Z]\d{7}$/,       requiresDocumentCapture: true, scanSides: 'front_only'     },
+  ],
+  KE: [
+    { key: 'national-id',     label: 'National ID',                    digits: 8,                     requiresDocumentCapture: true, scanSides: 'front_and_back' },
+    { key: 'passport',        label: 'Passport',                                                      requiresDocumentCapture: true, scanSides: 'front_only'     },
+  ],
+  ZA: [
+    { key: 'national-id',     label: 'National ID',                    digits: 13,                    requiresDocumentCapture: true, scanSides: 'front_and_back' },
+  ],
+  CI: [
+    { key: 'cni',             label: "CNI (Carte Nationale d'Identité)",                              requiresDocumentCapture: true, scanSides: 'front_and_back' },
+    { key: 'residence-card',  label: 'Residence Card',                                                requiresDocumentCapture: true, scanSides: 'front_and_back' },
+  ],
+} as const;
+
+const ALL_ID_TYPES = Object.values(ID_TYPES).flat();
+
+/**
+ * Returns true for IDs that skip document capture and go straight to the
+ * id-input form (user types their number manually). Nigeria: BVN, NIN, vNIN.
+ */
+export function isNumberOnlyIdType(idType: string): boolean {
+  const def = ALL_ID_TYPES.find((t) => t.key === idType);
+  return def ? !def.requiresDocumentCapture : false;
+}
+
+/** Returns true when the selected ID type requires a physical document scan. */
+export function requiresDocumentCapture(idType: string): boolean {
+  const def = ALL_ID_TYPES.find((t) => t.key === idType);
+  return def ? def.requiresDocumentCapture : true;
+}
+
+/**
+ * Returns the scan-sides configuration for a document ID type. Defaults to
+ * `'front_only'` when not explicitly set.
+ */
+export function getScanSides(idType: string): 'front_only' | 'front_and_back' {
+  const def = ALL_ID_TYPES.find((t) => t.key === idType);
+  return def?.scanSides ?? 'front_only';
+}
+
+// Card-guide / crop aspect (width ÷ height) for the live camera. Mirrors the
+// Flutter SDK's documentGuideAspect: ID-1 cards use 1.586; passports use a taller
+// 1.42 so the data page's bottom MRZ band isn't cropped off.
+export const CARD_GUIDE_ASPECT = 85.6 / 53.98; // ISO/IEC 7810 ID-1 ≈ 1.586
+export const PASSPORT_GUIDE_ASPECT = 1.42;
+
+export function documentGuideAspect(idType: string | null): number {
+  return idType === 'passport' ? PASSPORT_GUIDE_ASPECT : CARD_GUIDE_ASPECT;
+}
+
+export const COUNTRY_LABELS: Record<string, string> = {
+  NG: 'Nigeria',
+  GH: 'Ghana',
+  KE: 'Kenya',
+  ZA: 'South Africa',
+  CI: "Côte d'Ivoire",
+};

package/src/config/theme.ts

@@ -0,0 +1,186 @@
+// ---------------------------------------------------------------------------
+// Design tokens — ported from the Flutter SDK's `theme.dart` (MyazaColorScheme)
+// and the web SDK's `globals.css`. Token-based so `appearance` overrides cascade
+// (mirrors Flutter's `_applyAppearance`): set `primaryColor` and the whole tint
+// family follows.
+// ---------------------------------------------------------------------------
+
+import type { KYCAppearance } from '../types/config';
+
+export interface MyazaColorScheme {
+  background: string;
+  backgroundSecondary: string;
+  textDark: string;
+  textSecondary: string;
+  textMuted: string;
+  border: string;
+  primary: string;
+  /** Text/icon color on top of `primary` (e.g. button labels). */
+  onPrimary: string;
+  primary50: string;
+  primary100: string;
+  primary200: string;
+  gray300: string;
+  gray400: string;
+  success: string;
+  successBg: string;
+  error: string;
+  errorBg: string;
+  warning: string;
+  warningBg: string;
+  info: string;
+  infoBg: string;
+}
+
+export const LIGHT_COLORS: MyazaColorScheme = {
+  background: '#FFFFFF',
+  backgroundSecondary: '#F6F5FE',
+  textDark: '#070330',
+  textSecondary: '#5A5775',
+  textMuted: '#828197',
+  border: '#D3CFFC',
+  primary: '#5645F5',
+  onPrimary: '#FFFFFF',
+  primary50: '#F6F5FE',
+  primary100: '#E9E7FE',
+  primary200: '#D3CFFC',
+  gray300: '#CDCDD6',
+  gray400: '#ACABBA',
+  success: '#0DA211',
+  successBg: '#D8F4DC',
+  error: '#BD1B09',
+  errorBg: '#FCD8D8',
+  warning: '#FFC107',
+  warningBg: '#FFF1D6',
+  info: '#004FAF',
+  infoBg: '#C8E9FF',
+};
+
+export const DARK_COLORS: MyazaColorScheme = {
+  background: '#040218',
+  backgroundSecondary: '#0F0C2E',
+  textDark: '#F6F5FE',
+  textSecondary: '#ACABBA',
+  textMuted: '#5A5775',
+  border: '#302D53',
+  primary: '#7B6EF7',
+  onPrimary: '#FFFFFF',
+  primary50: '#1A1730',
+  primary100: '#2A2651',
+  primary200: '#3D3870',
+  gray300: '#302D53',
+  gray400: '#5A5775',
+  success: '#0DA211',
+  successBg: '#0B2B0C',
+  error: '#BD1B09',
+  errorBg: '#2B0A0A',
+  warning: '#FFC107',
+  warningBg: '#2B1B00',
+  info: '#004FAF',
+  infoBg: '#001B3B',
+};
+
+export type ThemeMode = 'light' | 'dark';
+
+export const radius = { xs: 8, sm: 12, md: 16, lg: 20, xl: 24, full: 999 } as const;
+export const spacing = { xs: 4, sm: 8, md: 16, lg: 24, xl: 32 } as const;
+export const sizing = {
+  buttonHeight: 48,
+  inputHeight: 48,
+  iconSize: 24,
+  avatarSize: 80,
+  cameraCircleSize: 260,
+} as const;
+
+/** Font families — registered via `expo-font` (see `loadMyazaFonts`). */
+export const fonts = {
+  heading: 'SpaceGrotesk_700Bold',
+  headingSemibold: 'SpaceGrotesk_600SemiBold',
+  body: 'Karla_400Regular',
+  bodyMedium: 'Karla_500Medium',
+  bodySemibold: 'Karla_600SemiBold',
+} as const;
+
+// ---------------------------------------------------------------------------
+// Color helpers — hex parsing + alpha blend (for deriving tints from primary)
+// ---------------------------------------------------------------------------
+
+interface Rgb {
+  r: number;
+  g: number;
+  b: number;
+}
+
+function parseHex(hex: string): Rgb | null {
+  const m = /^#?([0-9a-f]{6})$/i.exec(hex.trim());
+  if (!m) return null;
+  const n = parseInt(m[1]!, 16);
+  return { r: (n >> 16) & 0xff, g: (n >> 8) & 0xff, b: n & 0xff };
+}
+
+function toHex({ r, g, b }: Rgb): string {
+  const h = (v: number) => Math.round(Math.max(0, Math.min(255, v))).toString(16).padStart(2, '0');
+  return `#${h(r)}${h(g)}${h(b)}`;
+}
+
+/** Alpha-blends `fg` over `bg` at opacity `alpha` (0–1). */
+function alphaBlend(fg: string, bg: string, alpha: number): string {
+  const f = parseHex(fg);
+  const b = parseHex(bg);
+  if (!f || !b) return fg;
+  return toHex({
+    r: f.r * alpha + b.r * (1 - alpha),
+    g: f.g * alpha + b.g * (1 - alpha),
+    b: f.b * alpha + b.b * (1 - alpha),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Appearance mapping — overlay KYCAppearance onto a base scheme.
+// Mirrors Flutter's `_applyAppearance`: when `primaryColor` is set, derive the
+// 50/100/200 tint family from it (alpha-blended over the background); an explicit
+// `accentColor` overrides the 100 tint.
+// ---------------------------------------------------------------------------
+
+export function applyAppearance(
+  base: MyazaColorScheme,
+  appearance: KYCAppearance | undefined,
+): MyazaColorScheme {
+  if (!appearance) return base;
+
+  const background = appearance.backgroundColor ?? base.background;
+  const next: MyazaColorScheme = {
+    ...base,
+    background,
+    backgroundSecondary: appearance.surfaceColor ?? base.backgroundSecondary,
+    border: appearance.borderColor ?? base.border,
+    textDark: appearance.textColor ?? base.textDark,
+    onPrimary: appearance.primaryTextColor ?? base.onPrimary,
+  };
+
+  if (appearance.primaryColor) {
+    next.primary = appearance.primaryColor;
+    next.primary50 = alphaBlend(appearance.primaryColor, background, 0.04);
+    next.primary100 = alphaBlend(appearance.primaryColor, background, 0.1);
+    next.primary200 = alphaBlend(appearance.primaryColor, background, 0.2);
+  }
+  if (appearance.accentColor) {
+    next.primary100 = appearance.accentColor;
+  }
+
+  return next;
+}
+
+/** Resolves the active color scheme for a mode + appearance override. */
+export function resolveColors(mode: ThemeMode, appearance?: KYCAppearance): MyazaColorScheme {
+  return applyAppearance(mode === 'dark' ? DARK_COLORS : LIGHT_COLORS, appearance);
+}
+
+/**
+ * Surface tint for the KYC header chrome — mirrors Flutter's `kycHeaderSurface`.
+ * Dark themes get a branded lift over the background; light themes use the
+ * subtle secondary surface.
+ */
+export function headerSurface(colors: MyazaColorScheme, mode: ThemeMode): string {
+  return mode === 'dark' ? alphaBlend(colors.primary, colors.background, 0.18) : colors.backgroundSecondary;
+}