@moveris/shared 2.2.0 → 2.4.0

package/README.md

@@ -426,6 +426,11 @@ const status = getStatusMessage('capturing', DEFAULT_LOCALE);
 | `processing`        | "Processing..."                | API verification in progress |
 | `success`           | "Verification complete"        | Successful completion        |
 | `failed`            | "Verification failed"          | Failed verification          |
+| `eyes_not_visible`  | "Eyes not clearly visible"     | Eye region featureless       |
+| `eyes_shadowed`     | "Eyes are in shadow…"          | Eye region too dark          |
+| `eyes_overexposed`  | "Eye region overexposed…"      | Eye region too bright        |
+| `glasses_glare`     | "Glare detected…"              | Specular highlights on eyes  |
+| `eye_quality_poor`  | "Eye region quality is poor"   | Generic eye quality failure  |
 
 ---
 
@@ -452,6 +457,59 @@ const color = OVAL_GUIDE_COLORS[state];
 
 ---
 
+### Eye Region Quality Analysis
+
+Pre-request eye-region quality gate. Platform-agnostic functions that analyze RGBA pixel data from eye regions to detect shadows, glare, occlusion, and poor visibility.
+
+```typescript
+import {
+  checkEyeRegionQuality,
+  analyzeEyeRegionBrightness,
+  analyzeEyeRegionContrast,
+  detectSpecularHighlights,
+  EYE_QUALITY_THRESHOLDS,
+} from '@moveris/shared';
+
+// Combined quality check (recommended)
+const quality = checkEyeRegionQuality(eyeRegionPixels);
+console.log(quality.passed); // boolean
+console.log(quality.brightness); // 0-255
+console.log(quality.contrast); // standard deviation of luminance
+console.log(quality.hasGlare); // boolean
+console.log(quality.glareRatio); // 0-1
+console.log(quality.message); // user-facing feedback or null
+
+// Individual checks
+const brightness = analyzeEyeRegionBrightness(pixels);
+const contrast = analyzeEyeRegionContrast(pixels);
+const glareRatio = detectSpecularHighlights(pixels);
+```
+
+| Check       | Threshold             | Condition                               |
+| ----------- | --------------------- | --------------------------------------- |
+| Shadowed    | `minBrightness: 40`   | Average luminance too low               |
+| Overexposed | `maxBrightness: 230`  | Average luminance too high              |
+| Glare       | `maxGlareRatio: 0.15` | >15% of pixels are specular highlights  |
+| Occluded    | `minContrast: 12`     | Standard deviation of luminance too low |
+
+Custom thresholds can be passed as a second argument to `checkEyeRegionQuality()`.
+
+### Eye Region Landmarks
+
+Extract bounding boxes for left and right eye regions from MediaPipe 468-point face mesh landmarks.
+
+```typescript
+import { getEyeRegionBounds, EYE_LANDMARK_INDICES, validateFaceLandmarks } from '@moveris/shared';
+
+const bounds = getEyeRegionBounds(landmarks);
+if (bounds) {
+  console.log(bounds.leftEye); // { x, y, width, height } (normalized 0-1)
+  console.log(bounds.rightEye); // { x, y, width, height } (normalized 0-1)
+}
+```
+
+---
+
 ### Frame Analysis Utilities
 
 Utilities for assessing frame quality before submission.
@@ -527,6 +585,10 @@ import type {
   HeadPose,
   FaceLandmarkPoint,
   LandmarkValidationResult,
+  EyeRegionQuality,
+  EyeQualityThresholds,
+  EyeRegionBounds,
+  EyeRegionsBounds,
 } from '@moveris/shared';
 ```
 

package/dist/index.d.mts

@@ -1,5 +1,13 @@
 type Verdict = 'live' | 'fake';
-type FastCheckModel = '10' | '50' | '250' | 'hybrid-v2-10' | 'hybrid-v2-30' | 'hybrid-v2-50' | 'hybrid-v2-60' | 'hybrid-v2-90' | 'hybrid-v2-100' | 'hybrid-v2-125' | 'hybrid-v2-150' | 'hybrid-v2-250' | 'mixed-10' | 'mixed-30' | 'mixed-60' | 'mixed-90' | 'mixed-120' | 'mixed-150' | 'mixed-250';
+interface ModelEntry {
+    id: string;
+    label: string;
+    description: string;
+    min_frames: number;
+    deprecated: boolean;
+}
+type ModelsResponse = ModelEntry[];
+type FastCheckModel = '10' | '50' | '250' | 'hybrid-v2-10' | 'hybrid-v2-30' | 'hybrid-v2-50' | 'hybrid-v2-60' | 'hybrid-v2-90' | 'hybrid-v2-100' | 'hybrid-v2-125' | 'hybrid-v2-150' | 'hybrid-v2-250' | 'mixed-10' | 'mixed-30' | 'mixed-60' | 'mixed-90' | 'mixed-120' | 'mixed-150' | 'mixed-250' | 'mixed-10-v2' | 'mixed-30-v2' | 'mixed-60-v2' | 'mixed-90-v2' | 'mixed-120-v2' | (string & object);
 type StreamingStatus = 'buffering' | 'complete';
 type FrameSource = 'media' | 'live';
 type JobStatus = 'queued' | 'processing' | 'complete' | 'failed';
@@ -172,6 +180,7 @@ interface ModelConfig {
     minFrames: number;
     recommendedFrames: number;
     description: string;
+    deprecated: boolean;
 }
 declare const MODEL_CONFIGS: Record<FastCheckModel, ModelConfig>;
 interface HybridModelConfig {
@@ -184,6 +193,8 @@ interface HybridModelConfig {
 declare const HYBRID_MODEL_CONFIGS: Record<string, HybridModelConfig>;
 declare function getMinFramesForModel(model: FastCheckModel): number;
 declare function hasEnoughFrames(model: FastCheckModel, frameCount: number): boolean;
+declare function isDeprecatedModel(model: FastCheckModel): boolean;
+declare function getActiveModels(): ModelConfig[];
 
 interface Frame {
     index: number;
@@ -322,6 +333,21 @@ declare const LANDMARK_INDEX: {
     readonly UPPER_LIP: 13;
     readonly LOWER_LIP: 14;
 };
+declare const EYE_LANDMARK_INDICES: {
+    readonly RIGHT_EYE: readonly [33, 7, 163, 144, 145, 153, 154, 155, 133, 173, 157, 158, 159, 160, 161, 246];
+    readonly LEFT_EYE: readonly [362, 382, 381, 380, 374, 373, 390, 249, 263, 466, 388, 387, 386, 385, 384, 398];
+};
+interface EyeRegionBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface EyeRegionsBounds {
+    leftEye: EyeRegionBounds;
+    rightEye: EyeRegionBounds;
+}
+declare function getEyeRegionBounds(landmarks: FaceLandmarkPoint[]): EyeRegionsBounds | null;
 declare const LANDMARK_MIN_BOUND = 0.1;
 declare const LANDMARK_MAX_BOUND = 0.9;
 declare const MIN_LANDMARK_COUNT = 15;
@@ -435,6 +461,7 @@ declare class LivenessClient {
     private static extractCodeFromText;
     private requestWithRetry;
     health(): Promise<HealthResponse>;
+    getModels(): Promise<ModelEntry[]>;
     queueStats(): Promise<QueueStatsResponse>;
     fastCheck(frames: CapturedFrame[], options?: {
         sessionId?: string;
@@ -531,6 +558,7 @@ declare const API_ENDPOINTS: {
 declare const DEFAULT_ENDPOINT: "https://api.moveris.com";
 declare const API_PATHS: {
     readonly health: "/health";
+    readonly models: "/api/v1/models";
     readonly fastCheck: "/api/v1/fast-check";
     readonly fastCheckCrops: "/api/v1/fast-check-crops";
     readonly fastCheckStream: "/api/v1/fast-check-stream";
@@ -655,6 +683,11 @@ declare const FEEDBACK_MESSAGES: {
     readonly too_dark: "Low lighting - move to a brighter area";
     readonly backlit: "Backlit - try facing the light source";
     readonly hand_detected: "Remove hand from face";
+    readonly eyes_not_visible: "Eyes not clearly visible";
+    readonly eyes_shadowed: "Eyes are in shadow - improve lighting";
+    readonly eyes_overexposed: "Eye region overexposed - reduce lighting";
+    readonly glasses_glare: "Glare detected - adjust angle or remove glasses";
+    readonly eye_quality_poor: "Eye region quality is poor";
     readonly capturing: "Capturing...";
     readonly almost_done: "Almost done...";
     readonly verification_complete: "Verification complete";
@@ -708,4 +741,25 @@ interface RetryOptions {
 declare function retryWithBackoff<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
 declare function sleep(ms: number): Promise<void>;
 
-export { ALIGNMENT_THRESHOLD_CAPTURE, ALIGNMENT_THRESHOLD_GOOD, ALIGNMENT_THRESHOLD_PERFECT, ALIGNMENT_THRESHOLD_POOR, API_ENDPOINTS, API_ERROR_CODES, API_PATHS, AUTH_CONFIG, type ApiErrorCode, BACKLIT_RATIO_THRESHOLD, BLUR_THRESHOLD_MOBILE, BaseFrameCollector, type BlurAnalysis, type CaptureQualityState, type CapturedFrame, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_ENDPOINT, DEFAULT_FACE_DETECTION_TIERS, DEFAULT_GAZE_THRESHOLDS, DEFAULT_HAND_OCCLUSION_CONFIG, DEFAULT_LIVENESS_CONFIG, DEFAULT_LOCALE, DEFAULT_OVAL_REGION, DEFAULT_STABILIZER_CONFIG, DEFAULT_STATUS_MESSAGES, type DetectionResult, type DetectionSummary, type DetectorConfig, ERROR_MESSAGES, ERROR_MESSAGES_ES, ES_LOCALE, type ErrorResponse, FACE_CENTER_VERTICAL_OFFSET, FACE_CROP_OUTPUT_SIZE, FEEDBACK_MESSAGES, FRAME_BUFFER_CONFIG, FRAME_CONFIG, type FaceAlignmentResult, type FaceBoundingBox, type FaceDetectionTiers, type FaceInOvalResult, type FaceLandmarkPoint, type FaceVisibilityResult, type FastCheckCropsRequest, type FastCheckModel, type FastCheckRequest, type FastCheckResponse, type FastCheckStreamRequest, type FastCheckStreamResponse, type FeedbackLocale, type FeedbackMessageKey, type Frame, FrameBuffer, type FrameData, type FrameQualityResult, FrameQueue, type FrameSource, GOOD_ALIGNMENT, type GazeThresholds, HIGH_ALIGNMENT, HYBRID_MODEL_CONFIGS, type HandOcclusionConfig, type HeadPose, type HealthResponse, type Hybrid150CheckRequest, type Hybrid50CheckRequest, type HybridCheckRequest, type HybridCheckResponse, type HybridFrameData, type HybridModelConfig, IDEAL_CROP_MULTIPLIER, type JobStatus, type JobStatusResponse, LANDMARK_INDEX, LANDMARK_MAX_BOUND, LANDMARK_MIN_BOUND, LOW_LIGHT_THRESHOLD, type LandmarkValidationResult, type LightingAnalysis, LivenessApiError, type LivenessCallbacks, LivenessClient, type LivenessClientConfig, type LivenessConfig, type LivenessResult, type LivenessState, MAX_CROP_MULTIPLIER, MAX_FACE_PERCENTAGE_IN_CROP, MAX_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_CROP_MULTIPLIER, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelType, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, type OnErrorCallback, type OnFrameCapturedCallback, type OnProgressCallback, type OnResultCallback, type OnStateChangeCallback, type OvalGuideState, type OvalRegion, type QueueStatsResponse, RETRY_CONFIG, type RetryOptions, type StabilizationProgress, type StabilizationResult, type StabilizerConfig, type StatusMessageKey, type StreamingStatus, TARGET_FACE_PERCENTAGE_IN_CROP, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeLighting, calculateAdaptiveCropMultiplier, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkFrameQuality, decodeBase64, encodeBase64, generateSessionId, getApiErrorMessage, getCaptureQualityFeedback, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, retryWithBackoff, rgbaToGrayscale, sleep, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };
+interface EyeRegionQuality {
+    passed: boolean;
+    brightness: number;
+    contrast: number;
+    hasGlare: boolean;
+    glareRatio: number;
+    message: string | null;
+}
+interface EyeQualityThresholds {
+    minBrightness: number;
+    maxBrightness: number;
+    minContrast: number;
+    glarePixelThreshold: number;
+    maxGlareRatio: number;
+}
+declare const EYE_QUALITY_THRESHOLDS: EyeQualityThresholds;
+declare function analyzeEyeRegionBrightness(pixels: Uint8Array | Uint8ClampedArray): number;
+declare function analyzeEyeRegionContrast(pixels: Uint8Array | Uint8ClampedArray, meanBrightness?: number): number;
+declare function detectSpecularHighlights(pixels: Uint8Array | Uint8ClampedArray, threshold?: number): number;
+declare function checkEyeRegionQuality(pixels: Uint8Array | Uint8ClampedArray, thresholds?: EyeQualityThresholds): EyeRegionQuality;
+
+export { ALIGNMENT_THRESHOLD_CAPTURE, ALIGNMENT_THRESHOLD_GOOD, ALIGNMENT_THRESHOLD_PERFECT, ALIGNMENT_THRESHOLD_POOR, API_ENDPOINTS, API_ERROR_CODES, API_PATHS, AUTH_CONFIG, type ApiErrorCode, BACKLIT_RATIO_THRESHOLD, BLUR_THRESHOLD_MOBILE, BaseFrameCollector, type BlurAnalysis, type CaptureQualityState, type CapturedFrame, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_ENDPOINT, DEFAULT_FACE_DETECTION_TIERS, DEFAULT_GAZE_THRESHOLDS, DEFAULT_HAND_OCCLUSION_CONFIG, DEFAULT_LIVENESS_CONFIG, DEFAULT_LOCALE, DEFAULT_OVAL_REGION, DEFAULT_STABILIZER_CONFIG, DEFAULT_STATUS_MESSAGES, type DetectionResult, type DetectionSummary, type DetectorConfig, ERROR_MESSAGES, ERROR_MESSAGES_ES, ES_LOCALE, EYE_LANDMARK_INDICES, EYE_QUALITY_THRESHOLDS, type ErrorResponse, type EyeQualityThresholds, type EyeRegionBounds, type EyeRegionQuality, type EyeRegionsBounds, FACE_CENTER_VERTICAL_OFFSET, FACE_CROP_OUTPUT_SIZE, FEEDBACK_MESSAGES, FRAME_BUFFER_CONFIG, FRAME_CONFIG, type FaceAlignmentResult, type FaceBoundingBox, type FaceDetectionTiers, type FaceInOvalResult, type FaceLandmarkPoint, type FaceVisibilityResult, type FastCheckCropsRequest, type FastCheckModel, type FastCheckRequest, type FastCheckResponse, type FastCheckStreamRequest, type FastCheckStreamResponse, type FeedbackLocale, type FeedbackMessageKey, type Frame, FrameBuffer, type FrameData, type FrameQualityResult, FrameQueue, type FrameSource, GOOD_ALIGNMENT, type GazeThresholds, HIGH_ALIGNMENT, HYBRID_MODEL_CONFIGS, type HandOcclusionConfig, type HeadPose, type HealthResponse, type Hybrid150CheckRequest, type Hybrid50CheckRequest, type HybridCheckRequest, type HybridCheckResponse, type HybridFrameData, type HybridModelConfig, IDEAL_CROP_MULTIPLIER, type JobStatus, type JobStatusResponse, LANDMARK_INDEX, LANDMARK_MAX_BOUND, LANDMARK_MIN_BOUND, LOW_LIGHT_THRESHOLD, type LandmarkValidationResult, type LightingAnalysis, LivenessApiError, type LivenessCallbacks, LivenessClient, type LivenessClientConfig, type LivenessConfig, type LivenessResult, type LivenessState, MAX_CROP_MULTIPLIER, MAX_FACE_PERCENTAGE_IN_CROP, MAX_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_CROP_MULTIPLIER, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelEntry, type ModelType, type ModelsResponse, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, type OnErrorCallback, type OnFrameCapturedCallback, type OnProgressCallback, type OnResultCallback, type OnStateChangeCallback, type OvalGuideState, type OvalRegion, type QueueStatsResponse, RETRY_CONFIG, type RetryOptions, type StabilizationProgress, type StabilizationResult, type StabilizerConfig, type StatusMessageKey, type StreamingStatus, TARGET_FACE_PERCENTAGE_IN_CROP, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeEyeRegionBrightness, analyzeEyeRegionContrast, analyzeLighting, calculateAdaptiveCropMultiplier, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkEyeRegionQuality, checkFrameQuality, decodeBase64, detectSpecularHighlights, encodeBase64, generateSessionId, getActiveModels, getApiErrorMessage, getCaptureQualityFeedback, getEyeRegionBounds, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isDeprecatedModel, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, retryWithBackoff, rgbaToGrayscale, sleep, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };

package/dist/index.d.ts

@@ -1,5 +1,13 @@
 type Verdict = 'live' | 'fake';
-type FastCheckModel = '10' | '50' | '250' | 'hybrid-v2-10' | 'hybrid-v2-30' | 'hybrid-v2-50' | 'hybrid-v2-60' | 'hybrid-v2-90' | 'hybrid-v2-100' | 'hybrid-v2-125' | 'hybrid-v2-150' | 'hybrid-v2-250' | 'mixed-10' | 'mixed-30' | 'mixed-60' | 'mixed-90' | 'mixed-120' | 'mixed-150' | 'mixed-250';
+interface ModelEntry {
+    id: string;
+    label: string;
+    description: string;
+    min_frames: number;
+    deprecated: boolean;
+}
+type ModelsResponse = ModelEntry[];
+type FastCheckModel = '10' | '50' | '250' | 'hybrid-v2-10' | 'hybrid-v2-30' | 'hybrid-v2-50' | 'hybrid-v2-60' | 'hybrid-v2-90' | 'hybrid-v2-100' | 'hybrid-v2-125' | 'hybrid-v2-150' | 'hybrid-v2-250' | 'mixed-10' | 'mixed-30' | 'mixed-60' | 'mixed-90' | 'mixed-120' | 'mixed-150' | 'mixed-250' | 'mixed-10-v2' | 'mixed-30-v2' | 'mixed-60-v2' | 'mixed-90-v2' | 'mixed-120-v2' | (string & object);
 type StreamingStatus = 'buffering' | 'complete';
 type FrameSource = 'media' | 'live';
 type JobStatus = 'queued' | 'processing' | 'complete' | 'failed';
@@ -172,6 +180,7 @@ interface ModelConfig {
     minFrames: number;
     recommendedFrames: number;
     description: string;
+    deprecated: boolean;
 }
 declare const MODEL_CONFIGS: Record<FastCheckModel, ModelConfig>;
 interface HybridModelConfig {
@@ -184,6 +193,8 @@ interface HybridModelConfig {
 declare const HYBRID_MODEL_CONFIGS: Record<string, HybridModelConfig>;
 declare function getMinFramesForModel(model: FastCheckModel): number;
 declare function hasEnoughFrames(model: FastCheckModel, frameCount: number): boolean;
+declare function isDeprecatedModel(model: FastCheckModel): boolean;
+declare function getActiveModels(): ModelConfig[];
 
 interface Frame {
     index: number;
@@ -322,6 +333,21 @@ declare const LANDMARK_INDEX: {
     readonly UPPER_LIP: 13;
     readonly LOWER_LIP: 14;
 };
+declare const EYE_LANDMARK_INDICES: {
+    readonly RIGHT_EYE: readonly [33, 7, 163, 144, 145, 153, 154, 155, 133, 173, 157, 158, 159, 160, 161, 246];
+    readonly LEFT_EYE: readonly [362, 382, 381, 380, 374, 373, 390, 249, 263, 466, 388, 387, 386, 385, 384, 398];
+};
+interface EyeRegionBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface EyeRegionsBounds {
+    leftEye: EyeRegionBounds;
+    rightEye: EyeRegionBounds;
+}
+declare function getEyeRegionBounds(landmarks: FaceLandmarkPoint[]): EyeRegionsBounds | null;
 declare const LANDMARK_MIN_BOUND = 0.1;
 declare const LANDMARK_MAX_BOUND = 0.9;
 declare const MIN_LANDMARK_COUNT = 15;
@@ -435,6 +461,7 @@ declare class LivenessClient {
     private static extractCodeFromText;
     private requestWithRetry;
     health(): Promise<HealthResponse>;
+    getModels(): Promise<ModelEntry[]>;
     queueStats(): Promise<QueueStatsResponse>;
     fastCheck(frames: CapturedFrame[], options?: {
         sessionId?: string;
@@ -531,6 +558,7 @@ declare const API_ENDPOINTS: {
 declare const DEFAULT_ENDPOINT: "https://api.moveris.com";
 declare const API_PATHS: {
     readonly health: "/health";
+    readonly models: "/api/v1/models";
     readonly fastCheck: "/api/v1/fast-check";
     readonly fastCheckCrops: "/api/v1/fast-check-crops";
     readonly fastCheckStream: "/api/v1/fast-check-stream";
@@ -655,6 +683,11 @@ declare const FEEDBACK_MESSAGES: {
     readonly too_dark: "Low lighting - move to a brighter area";
     readonly backlit: "Backlit - try facing the light source";
     readonly hand_detected: "Remove hand from face";
+    readonly eyes_not_visible: "Eyes not clearly visible";
+    readonly eyes_shadowed: "Eyes are in shadow - improve lighting";
+    readonly eyes_overexposed: "Eye region overexposed - reduce lighting";
+    readonly glasses_glare: "Glare detected - adjust angle or remove glasses";
+    readonly eye_quality_poor: "Eye region quality is poor";
     readonly capturing: "Capturing...";
     readonly almost_done: "Almost done...";
     readonly verification_complete: "Verification complete";
@@ -708,4 +741,25 @@ interface RetryOptions {
 declare function retryWithBackoff<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
 declare function sleep(ms: number): Promise<void>;
 
-export { ALIGNMENT_THRESHOLD_CAPTURE, ALIGNMENT_THRESHOLD_GOOD, ALIGNMENT_THRESHOLD_PERFECT, ALIGNMENT_THRESHOLD_POOR, API_ENDPOINTS, API_ERROR_CODES, API_PATHS, AUTH_CONFIG, type ApiErrorCode, BACKLIT_RATIO_THRESHOLD, BLUR_THRESHOLD_MOBILE, BaseFrameCollector, type BlurAnalysis, type CaptureQualityState, type CapturedFrame, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_ENDPOINT, DEFAULT_FACE_DETECTION_TIERS, DEFAULT_GAZE_THRESHOLDS, DEFAULT_HAND_OCCLUSION_CONFIG, DEFAULT_LIVENESS_CONFIG, DEFAULT_LOCALE, DEFAULT_OVAL_REGION, DEFAULT_STABILIZER_CONFIG, DEFAULT_STATUS_MESSAGES, type DetectionResult, type DetectionSummary, type DetectorConfig, ERROR_MESSAGES, ERROR_MESSAGES_ES, ES_LOCALE, type ErrorResponse, FACE_CENTER_VERTICAL_OFFSET, FACE_CROP_OUTPUT_SIZE, FEEDBACK_MESSAGES, FRAME_BUFFER_CONFIG, FRAME_CONFIG, type FaceAlignmentResult, type FaceBoundingBox, type FaceDetectionTiers, type FaceInOvalResult, type FaceLandmarkPoint, type FaceVisibilityResult, type FastCheckCropsRequest, type FastCheckModel, type FastCheckRequest, type FastCheckResponse, type FastCheckStreamRequest, type FastCheckStreamResponse, type FeedbackLocale, type FeedbackMessageKey, type Frame, FrameBuffer, type FrameData, type FrameQualityResult, FrameQueue, type FrameSource, GOOD_ALIGNMENT, type GazeThresholds, HIGH_ALIGNMENT, HYBRID_MODEL_CONFIGS, type HandOcclusionConfig, type HeadPose, type HealthResponse, type Hybrid150CheckRequest, type Hybrid50CheckRequest, type HybridCheckRequest, type HybridCheckResponse, type HybridFrameData, type HybridModelConfig, IDEAL_CROP_MULTIPLIER, type JobStatus, type JobStatusResponse, LANDMARK_INDEX, LANDMARK_MAX_BOUND, LANDMARK_MIN_BOUND, LOW_LIGHT_THRESHOLD, type LandmarkValidationResult, type LightingAnalysis, LivenessApiError, type LivenessCallbacks, LivenessClient, type LivenessClientConfig, type LivenessConfig, type LivenessResult, type LivenessState, MAX_CROP_MULTIPLIER, MAX_FACE_PERCENTAGE_IN_CROP, MAX_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_CROP_MULTIPLIER, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelType, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, type OnErrorCallback, type OnFrameCapturedCallback, type OnProgressCallback, type OnResultCallback, type OnStateChangeCallback, type OvalGuideState, type OvalRegion, type QueueStatsResponse, RETRY_CONFIG, type RetryOptions, type StabilizationProgress, type StabilizationResult, type StabilizerConfig, type StatusMessageKey, type StreamingStatus, TARGET_FACE_PERCENTAGE_IN_CROP, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeLighting, calculateAdaptiveCropMultiplier, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkFrameQuality, decodeBase64, encodeBase64, generateSessionId, getApiErrorMessage, getCaptureQualityFeedback, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, retryWithBackoff, rgbaToGrayscale, sleep, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };
+interface EyeRegionQuality {
+    passed: boolean;
+    brightness: number;
+    contrast: number;
+    hasGlare: boolean;
+    glareRatio: number;
+    message: string | null;
+}
+interface EyeQualityThresholds {
+    minBrightness: number;
+    maxBrightness: number;
+    minContrast: number;
+    glarePixelThreshold: number;
+    maxGlareRatio: number;
+}
+declare const EYE_QUALITY_THRESHOLDS: EyeQualityThresholds;
+declare function analyzeEyeRegionBrightness(pixels: Uint8Array | Uint8ClampedArray): number;
+declare function analyzeEyeRegionContrast(pixels: Uint8Array | Uint8ClampedArray, meanBrightness?: number): number;
+declare function detectSpecularHighlights(pixels: Uint8Array | Uint8ClampedArray, threshold?: number): number;
+declare function checkEyeRegionQuality(pixels: Uint8Array | Uint8ClampedArray, thresholds?: EyeQualityThresholds): EyeRegionQuality;
+
+export { ALIGNMENT_THRESHOLD_CAPTURE, ALIGNMENT_THRESHOLD_GOOD, ALIGNMENT_THRESHOLD_PERFECT, ALIGNMENT_THRESHOLD_POOR, API_ENDPOINTS, API_ERROR_CODES, API_PATHS, AUTH_CONFIG, type ApiErrorCode, BACKLIT_RATIO_THRESHOLD, BLUR_THRESHOLD_MOBILE, BaseFrameCollector, type BlurAnalysis, type CaptureQualityState, type CapturedFrame, type CropData, DEFAULT_BLUR_THRESHOLD, DEFAULT_ENDPOINT, DEFAULT_FACE_DETECTION_TIERS, DEFAULT_GAZE_THRESHOLDS, DEFAULT_HAND_OCCLUSION_CONFIG, DEFAULT_LIVENESS_CONFIG, DEFAULT_LOCALE, DEFAULT_OVAL_REGION, DEFAULT_STABILIZER_CONFIG, DEFAULT_STATUS_MESSAGES, type DetectionResult, type DetectionSummary, type DetectorConfig, ERROR_MESSAGES, ERROR_MESSAGES_ES, ES_LOCALE, EYE_LANDMARK_INDICES, EYE_QUALITY_THRESHOLDS, type ErrorResponse, type EyeQualityThresholds, type EyeRegionBounds, type EyeRegionQuality, type EyeRegionsBounds, FACE_CENTER_VERTICAL_OFFSET, FACE_CROP_OUTPUT_SIZE, FEEDBACK_MESSAGES, FRAME_BUFFER_CONFIG, FRAME_CONFIG, type FaceAlignmentResult, type FaceBoundingBox, type FaceDetectionTiers, type FaceInOvalResult, type FaceLandmarkPoint, type FaceVisibilityResult, type FastCheckCropsRequest, type FastCheckModel, type FastCheckRequest, type FastCheckResponse, type FastCheckStreamRequest, type FastCheckStreamResponse, type FeedbackLocale, type FeedbackMessageKey, type Frame, FrameBuffer, type FrameData, type FrameQualityResult, FrameQueue, type FrameSource, GOOD_ALIGNMENT, type GazeThresholds, HIGH_ALIGNMENT, HYBRID_MODEL_CONFIGS, type HandOcclusionConfig, type HeadPose, type HealthResponse, type Hybrid150CheckRequest, type Hybrid50CheckRequest, type HybridCheckRequest, type HybridCheckResponse, type HybridFrameData, type HybridModelConfig, IDEAL_CROP_MULTIPLIER, type JobStatus, type JobStatusResponse, LANDMARK_INDEX, LANDMARK_MAX_BOUND, LANDMARK_MIN_BOUND, LOW_LIGHT_THRESHOLD, type LandmarkValidationResult, type LightingAnalysis, LivenessApiError, type LivenessCallbacks, LivenessClient, type LivenessClientConfig, type LivenessConfig, type LivenessResult, type LivenessState, MAX_CROP_MULTIPLIER, MAX_FACE_PERCENTAGE_IN_CROP, MAX_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_CROP_MULTIPLIER, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelEntry, type ModelType, type ModelsResponse, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, type OnErrorCallback, type OnFrameCapturedCallback, type OnProgressCallback, type OnResultCallback, type OnStateChangeCallback, type OvalGuideState, type OvalRegion, type QueueStatsResponse, RETRY_CONFIG, type RetryOptions, type StabilizationProgress, type StabilizationResult, type StabilizerConfig, type StatusMessageKey, type StreamingStatus, TARGET_FACE_PERCENTAGE_IN_CROP, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeEyeRegionBrightness, analyzeEyeRegionContrast, analyzeLighting, calculateAdaptiveCropMultiplier, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkEyeRegionQuality, checkFrameQuality, decodeBase64, detectSpecularHighlights, encodeBase64, generateSessionId, getActiveModels, getApiErrorMessage, getCaptureQualityFeedback, getEyeRegionBounds, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isDeprecatedModel, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, retryWithBackoff, rgbaToGrayscale, sleep, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };

package/dist/index.js

@@ -44,6 +44,8 @@ __export(index_exports, {
   ERROR_MESSAGES: () => ERROR_MESSAGES,
   ERROR_MESSAGES_ES: () => ERROR_MESSAGES_ES,
   ES_LOCALE: () => ES_LOCALE,
+  EYE_LANDMARK_INDICES: () => EYE_LANDMARK_INDICES,
+  EYE_QUALITY_THRESHOLDS: () => EYE_QUALITY_THRESHOLDS,
   FACE_CENTER_VERTICAL_OFFSET: () => FACE_CENTER_VERTICAL_OFFSET,
   FACE_CROP_OUTPUT_SIZE: () => FACE_CROP_OUTPUT_SIZE,
   FEEDBACK_MESSAGES: () => FEEDBACK_MESSAGES,
@@ -77,23 +79,30 @@ __export(index_exports, {
   RETRY_CONFIG: () => RETRY_CONFIG,
   TARGET_FACE_PERCENTAGE_IN_CROP: () => TARGET_FACE_PERCENTAGE_IN_CROP,
   analyzeBlur: () => analyzeBlur,
+  analyzeEyeRegionBrightness: () => analyzeEyeRegionBrightness,
+  analyzeEyeRegionContrast: () => analyzeEyeRegionContrast,
   analyzeLighting: () => analyzeLighting,
   calculateAdaptiveCropMultiplier: () => calculateAdaptiveCropMultiplier,
   calculateBrightness: () => calculateBrightness,
   calculateFaceAlignment: () => calculateFaceAlignment,
   calculateFaceCropRegion: () => calculateFaceCropRegion,
   canCaptureFrame: () => canCaptureFrame,
+  checkEyeRegionQuality: () => checkEyeRegionQuality,
   checkFrameQuality: () => checkFrameQuality,
   decodeBase64: () => decodeBase64,
+  detectSpecularHighlights: () => detectSpecularHighlights,
   encodeBase64: () => encodeBase64,
   generateSessionId: () => generateSessionId,
+  getActiveModels: () => getActiveModels,
   getApiErrorMessage: () => getApiErrorMessage,
   getCaptureQualityFeedback: () => getCaptureQualityFeedback,
+  getEyeRegionBounds: () => getEyeRegionBounds,
   getFeedbackMessage: () => getFeedbackMessage,
   getMinFramesForModel: () => getMinFramesForModel,
   getOvalGuideState: () => getOvalGuideState,
   getStatusMessage: () => getStatusMessage,
   hasEnoughFrames: () => hasEnoughFrames,
+  isDeprecatedModel: () => isDeprecatedModel,
   isFaceCropFullyInFrame: () => isFaceCropFullyInFrame,
   isFaceFullyVisible: () => isFaceFullyVisible,
   isFaceInOval: () => isFaceInOval,
@@ -125,6 +134,7 @@ var API_ENDPOINTS = {
 var DEFAULT_ENDPOINT = API_ENDPOINTS.production;
 var API_PATHS = {
   health: "/health",
+  models: "/api/v1/models",
   fastCheck: "/api/v1/fast-check",
   fastCheckCrops: "/api/v1/fast-check-crops",
   fastCheckStream: "/api/v1/fast-check-stream",
@@ -412,6 +422,14 @@ var LivenessClient = class _LivenessClient {
   async health() {
     return this.request(API_PATHS.health);
   }
+  /**
+   * Fetch the full model registry from the API.
+   * Includes all models with their deprecated status.
+   * Use this instead of the local MODEL_CONFIGS for a live list.
+   */
+  async getModels() {
+    return this.request(API_PATHS.models);
+  }
   /**
    * Get queue statistics
    */
@@ -861,117 +879,172 @@ var MODEL_CONFIGS = {
     type: "10",
     minFrames: 10,
     recommendedFrames: 10,
-    description: "Fast model - 10 frames, quick verification"
+    description: "Fast model - 10 frames, quick verification",
+    deprecated: false
   },
   "50": {
     type: "50",
     minFrames: 50,
     recommendedFrames: 50,
-    description: "Balanced model - 50 frames, good accuracy"
+    description: "Balanced model - 50 frames, good accuracy",
+    deprecated: false
   },
   "250": {
     type: "250",
     minFrames: 250,
     recommendedFrames: 250,
-    description: "High-accuracy model - 250 frames, best accuracy"
+    description: "High-accuracy model - 250 frames, best accuracy",
+    deprecated: false
   },
   // Hybrid V2 models with physiological features
   "hybrid-v2-10": {
     type: "hybrid-v2-10",
     minFrames: 10,
     recommendedFrames: 10,
-    description: "Hybrid V2 10-frame model with physio features"
+    description: "Hybrid V2 10-frame model with physio features",
+    deprecated: false
   },
   "hybrid-v2-30": {
     type: "hybrid-v2-30",
     minFrames: 30,
     recommendedFrames: 30,
-    description: "Hybrid V2 30-frame model with physio features"
+    description: "Hybrid V2 30-frame model with physio features",
+    deprecated: false
   },
   "hybrid-v2-50": {
     type: "hybrid-v2-50",
     minFrames: 50,
     recommendedFrames: 50,
-    description: "Hybrid V2 50-frame model with physio features"
+    description: "Hybrid V2 50-frame model with physio features",
+    deprecated: false
   },
   "hybrid-v2-60": {
     type: "hybrid-v2-60",
     minFrames: 60,
     recommendedFrames: 60,
-    description: "Hybrid V2 60-frame model with physio features"
+    description: "Hybrid V2 60-frame model with physio features",
+    deprecated: false
   },
   "hybrid-v2-90": {
     type: "hybrid-v2-90",
     minFrames: 90,
     recommendedFrames: 90,
-    description: "Hybrid V2 90-frame model with physio features"
+    description: "Hybrid V2 90-frame model with physio features",
+    deprecated: false
   },
   "hybrid-v2-100": {
     type: "hybrid-v2-100",
     minFrames: 100,
     recommendedFrames: 100,
-    description: "Hybrid V2 100-frame model with physio features"
+    description: "Hybrid V2 100-frame model with physio features",
+    deprecated: false
   },
   "hybrid-v2-125": {
     type: "hybrid-v2-125",
     minFrames: 125,
     recommendedFrames: 125,
-    description: "Hybrid V2 125-frame model with physio features"
+    description: "Hybrid V2 125-frame model with physio features",
+    deprecated: false
   },
   "hybrid-v2-150": {
     type: "hybrid-v2-150",
     minFrames: 150,
     recommendedFrames: 150,
-    description: "Hybrid V2 150-frame model with physio features"
+    description: "Hybrid V2 150-frame model with physio features",
+    deprecated: false
   },
   "hybrid-v2-250": {
     type: "hybrid-v2-250",
     minFrames: 250,
     recommendedFrames: 250,
-    description: "Hybrid V2 250-frame model with physio features"
+    description: "Hybrid V2 250-frame model with physio features",
+    deprecated: false
   },
-  // Mixed models (FastLivenessDetector with mixed-trained weights)
+  // Mixed V1 models — deprecated, use mixed-*-v2 equivalents instead
   "mixed-10": {
     type: "mixed-10",
     minFrames: 10,
     recommendedFrames: 10,
-    description: "Mixed 10-frame model"
+    description: "Mixed 10-frame model",
+    deprecated: true
   },
   "mixed-30": {
     type: "mixed-30",
     minFrames: 30,
     recommendedFrames: 30,
-    description: "Mixed 30-frame model"
+    description: "Mixed 30-frame model",
+    deprecated: true
   },
   "mixed-60": {
     type: "mixed-60",
     minFrames: 60,
     recommendedFrames: 60,
-    description: "Mixed 60-frame model"
+    description: "Mixed 60-frame model",
+    deprecated: true
   },
   "mixed-90": {
     type: "mixed-90",
     minFrames: 90,
     recommendedFrames: 90,
-    description: "Mixed 90-frame model"
+    description: "Mixed 90-frame model",
+    deprecated: true
   },
   "mixed-120": {
     type: "mixed-120",
     minFrames: 120,
     recommendedFrames: 120,
-    description: "Mixed 120-frame model"
+    description: "Mixed 120-frame model",
+    deprecated: true
   },
   "mixed-150": {
     type: "mixed-150",
     minFrames: 150,
     recommendedFrames: 150,
-    description: "Mixed 150-frame model"
+    description: "Mixed 150-frame model",
+    deprecated: true
   },
   "mixed-250": {
     type: "mixed-250",
     minFrames: 250,
     recommendedFrames: 250,
-    description: "Mixed 250-frame model"
+    description: "Mixed 250-frame model",
+    deprecated: true
+  },
+  // Mixed V2 models (exp_042 checkpoints — EER: 4.0% / AUC: 0.991 at 30f)
+  "mixed-10-v2": {
+    type: "mixed-10-v2",
+    minFrames: 10,
+    recommendedFrames: 10,
+    description: "Mixed V2 10-frame model",
+    deprecated: false
+  },
+  "mixed-30-v2": {
+    type: "mixed-30-v2",
+    minFrames: 30,
+    recommendedFrames: 30,
+    description: "Mixed V2 30-frame model (recommended \u2014 95.7% balanced accuracy)",
+    deprecated: false
+  },
+  "mixed-60-v2": {
+    type: "mixed-60-v2",
+    minFrames: 60,
+    recommendedFrames: 60,
+    description: "Mixed V2 60-frame model",
+    deprecated: false
+  },
+  "mixed-90-v2": {
+    type: "mixed-90-v2",
+    minFrames: 90,
+    recommendedFrames: 90,
+    description: "Mixed V2 90-frame model",
+    deprecated: false
+  },
+  "mixed-120-v2": {
+    type: "mixed-120-v2",
+    minFrames: 120,
+    recommendedFrames: 120,
+    description: "Mixed V2 120-frame model",
+    deprecated: false
   }
 };
 var HYBRID_MODEL_CONFIGS = {
@@ -991,10 +1064,16 @@ var HYBRID_MODEL_CONFIGS = {
   }
 };
 function getMinFramesForModel(model) {
-  return MODEL_CONFIGS[model].minFrames;
+  return MODEL_CONFIGS[model]?.minFrames ?? 10;
 }
 function hasEnoughFrames(model, frameCount) {
-  return frameCount >= MODEL_CONFIGS[model].minFrames;
+  return frameCount >= getMinFramesForModel(model);
+}
+function isDeprecatedModel(model) {
+  return MODEL_CONFIGS[model]?.deprecated ?? false;
+}
+function getActiveModels() {
+  return Object.values(MODEL_CONFIGS).filter((c) => !c.deprecated);
 }
 
 // src/types/detectors.ts
@@ -1161,6 +1240,12 @@ var FEEDBACK_MESSAGES = {
   backlit: "Backlit - try facing the light source",
   // Hand occlusion
   hand_detected: "Remove hand from face",
+  // Eye region quality
+  eyes_not_visible: "Eyes not clearly visible",
+  eyes_shadowed: "Eyes are in shadow - improve lighting",
+  eyes_overexposed: "Eye region overexposed - reduce lighting",
+  glasses_glare: "Glare detected - adjust angle or remove glasses",
+  eye_quality_poor: "Eye region quality is poor",
   // Progress messages
   capturing: "Capturing...",
   almost_done: "Almost done...",
@@ -1212,6 +1297,12 @@ var ES_LOCALE = {
     backlit: "Contraluz - intenta mirar hacia la fuente de luz",
     // Hand occlusion
     hand_detected: "Retira la mano del rostro",
+    // Eye region quality
+    eyes_not_visible: "Ojos no visibles claramente",
+    eyes_shadowed: "Ojos en sombra - mejora la iluminaci\xF3n",
+    eyes_overexposed: "Regi\xF3n de ojos sobreexpuesta - reduce la iluminaci\xF3n",
+    glasses_glare: "Reflejo detectado - ajusta el \xE1ngulo o retira los lentes",
+    eye_quality_poor: "Calidad de la regi\xF3n de ojos insuficiente",
     // Progress messages
     capturing: "Capturando...",
     almost_done: "Casi listo...",
@@ -1295,7 +1386,7 @@ function validateTimestamp(timestamp) {
 }
 function validateFrameCount(model, frameCount) {
   const config = MODEL_CONFIGS[model];
-  const required = config.minFrames;
+  const required = config?.minFrames ?? 10;
   return {
     valid: frameCount >= required,
     required,
@@ -1645,6 +1736,44 @@ var LANDMARK_INDEX = {
   /** Lower lip center */
   LOWER_LIP: 14
 };
+var EYE_LANDMARK_INDICES = {
+  /** Right eye contour (viewer's left) */
+  RIGHT_EYE: [33, 7, 163, 144, 145, 153, 154, 155, 133, 173, 157, 158, 159, 160, 161, 246],
+  /** Left eye contour (viewer's right) */
+  LEFT_EYE: [362, 382, 381, 380, 374, 373, 390, 249, 263, 466, 388, 387, 386, 385, 384, 398]
+};
+function getEyeRegionBounds(landmarks) {
+  if (landmarks.length < 468) return null;
+  const PADDING = 0.2;
+  function computeBounds(indices) {
+    let minX = 1;
+    let minY = 1;
+    let maxX = 0;
+    let maxY = 0;
+    for (const idx of indices) {
+      const lm = landmarks[idx];
+      if (!lm) continue;
+      if (lm.x < minX) minX = lm.x;
+      if (lm.y < minY) minY = lm.y;
+      if (lm.x > maxX) maxX = lm.x;
+      if (lm.y > maxY) maxY = lm.y;
+    }
+    const width = maxX - minX;
+    const height = maxY - minY;
+    const padX = width * PADDING;
+    const padY = height * PADDING;
+    return {
+      x: Math.max(0, minX - padX),
+      y: Math.max(0, minY - padY),
+      width: Math.min(1 - Math.max(0, minX - padX), width + padX * 2),
+      height: Math.min(1 - Math.max(0, minY - padY), height + padY * 2)
+    };
+  }
+  return {
+    rightEye: computeBounds(EYE_LANDMARK_INDICES.RIGHT_EYE),
+    leftEye: computeBounds(EYE_LANDMARK_INDICES.LEFT_EYE)
+  };
+}
 var LANDMARK_MIN_BOUND = 0.1;
 var LANDMARK_MAX_BOUND = 0.9;
 var MIN_LANDMARK_COUNT = 15;
@@ -1666,6 +1795,115 @@ function validateFaceLandmarks(landmarks) {
   }
   return { valid: true };
 }
+
+// src/utils/eyeRegionAnalysis.ts
+var EYE_QUALITY_THRESHOLDS = {
+  minBrightness: 40,
+  maxBrightness: 230,
+  minContrast: 12,
+  glarePixelThreshold: 240,
+  maxGlareRatio: 0.15
+};
+function rgbaToLuminance(r, g, b) {
+  return 0.299 * r + 0.587 * g + 0.114 * b;
+}
+function analyzeEyeRegionBrightness(pixels) {
+  const pixelCount = pixels.length / 4;
+  if (pixelCount === 0) return 0;
+  let totalLuminance = 0;
+  for (let i = 0; i < pixels.length; i += 4) {
+    totalLuminance += rgbaToLuminance(pixels[i], pixels[i + 1], pixels[i + 2]);
+  }
+  return totalLuminance / pixelCount;
+}
+function analyzeEyeRegionContrast(pixels, meanBrightness) {
+  const pixelCount = pixels.length / 4;
+  if (pixelCount === 0) return 0;
+  const mean = meanBrightness ?? analyzeEyeRegionBrightness(pixels);
+  let sumSqDiff = 0;
+  for (let i = 0; i < pixels.length; i += 4) {
+    const lum = rgbaToLuminance(pixels[i], pixels[i + 1], pixels[i + 2]);
+    const diff = lum - mean;
+    sumSqDiff += diff * diff;
+  }
+  return Math.sqrt(sumSqDiff / pixelCount);
+}
+function detectSpecularHighlights(pixels, threshold = EYE_QUALITY_THRESHOLDS.glarePixelThreshold) {
+  const pixelCount = pixels.length / 4;
+  if (pixelCount === 0) return 0;
+  let glareCount = 0;
+  for (let i = 0; i < pixels.length; i += 4) {
+    const lum = rgbaToLuminance(pixels[i], pixels[i + 1], pixels[i + 2]);
+    if (lum >= threshold) {
+      glareCount++;
+    }
+  }
+  return glareCount / pixelCount;
+}
+function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
+  if (pixels.length < 4) {
+    return {
+      passed: false,
+      brightness: 0,
+      contrast: 0,
+      hasGlare: false,
+      glareRatio: 0,
+      message: "Eyes not clearly visible"
+    };
+  }
+  const brightness = analyzeEyeRegionBrightness(pixels);
+  const contrast = analyzeEyeRegionContrast(pixels, brightness);
+  const glareRatio = detectSpecularHighlights(pixels, thresholds.glarePixelThreshold);
+  const hasGlare = glareRatio > thresholds.maxGlareRatio;
+  if (brightness < thresholds.minBrightness) {
+    return {
+      passed: false,
+      brightness,
+      contrast,
+      hasGlare,
+      glareRatio,
+      message: "Eyes are in shadow - improve lighting"
+    };
+  }
+  if (brightness > thresholds.maxBrightness) {
+    return {
+      passed: false,
+      brightness,
+      contrast,
+      hasGlare,
+      glareRatio,
+      message: "Eye region overexposed - reduce lighting"
+    };
+  }
+  if (hasGlare) {
+    return {
+      passed: false,
+      brightness,
+      contrast,
+      hasGlare,
+      glareRatio,
+      message: "Glare detected - adjust angle or remove glasses"
+    };
+  }
+  if (contrast < thresholds.minContrast) {
+    return {
+      passed: false,
+      brightness,
+      contrast,
+      hasGlare,
+      glareRatio,
+      message: "Eyes not clearly visible"
+    };
+  }
+  return {
+    passed: true,
+    brightness,
+    contrast,
+    hasGlare,
+    glareRatio,
+    message: null
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ALIGNMENT_THRESHOLD_CAPTURE,
@@ -1692,6 +1930,8 @@ function validateFaceLandmarks(landmarks) {
   ERROR_MESSAGES,
   ERROR_MESSAGES_ES,
   ES_LOCALE,
+  EYE_LANDMARK_INDICES,
+  EYE_QUALITY_THRESHOLDS,
   FACE_CENTER_VERTICAL_OFFSET,
   FACE_CROP_OUTPUT_SIZE,
   FEEDBACK_MESSAGES,
@@ -1725,23 +1965,30 @@ function validateFaceLandmarks(landmarks) {
   RETRY_CONFIG,
   TARGET_FACE_PERCENTAGE_IN_CROP,
   analyzeBlur,
+  analyzeEyeRegionBrightness,
+  analyzeEyeRegionContrast,
   analyzeLighting,
   calculateAdaptiveCropMultiplier,
   calculateBrightness,
   calculateFaceAlignment,
   calculateFaceCropRegion,
   canCaptureFrame,
+  checkEyeRegionQuality,
   checkFrameQuality,
   decodeBase64,
+  detectSpecularHighlights,
   encodeBase64,
   generateSessionId,
+  getActiveModels,
   getApiErrorMessage,
   getCaptureQualityFeedback,
+  getEyeRegionBounds,
   getFeedbackMessage,
   getMinFramesForModel,
   getOvalGuideState,
   getStatusMessage,
   hasEnoughFrames,
+  isDeprecatedModel,
   isFaceCropFullyInFrame,
   isFaceFullyVisible,
   isFaceInOval,

package/dist/index.mjs

@@ -7,6 +7,7 @@ var API_ENDPOINTS = {
 var DEFAULT_ENDPOINT = API_ENDPOINTS.production;
 var API_PATHS = {
   health: "/health",
+  models: "/api/v1/models",
   fastCheck: "/api/v1/fast-check",
   fastCheckCrops: "/api/v1/fast-check-crops",
   fastCheckStream: "/api/v1/fast-check-stream",
@@ -294,6 +295,14 @@ var LivenessClient = class _LivenessClient {
   async health() {
     return this.request(API_PATHS.health);
   }
+  /**
+   * Fetch the full model registry from the API.
+   * Includes all models with their deprecated status.
+   * Use this instead of the local MODEL_CONFIGS for a live list.
+   */
+  async getModels() {
+    return this.request(API_PATHS.models);
+  }
   /**
    * Get queue statistics
    */
@@ -743,117 +752,172 @@ var MODEL_CONFIGS = {
     type: "10",
     minFrames: 10,
     recommendedFrames: 10,
-    description: "Fast model - 10 frames, quick verification"
+    description: "Fast model - 10 frames, quick verification",
+    deprecated: false
   },
   "50": {
     type: "50",
     minFrames: 50,
     recommendedFrames: 50,
-    description: "Balanced model - 50 frames, good accuracy"
+    description: "Balanced model - 50 frames, good accuracy",
+    deprecated: false
   },
   "250": {
     type: "250",
     minFrames: 250,
     recommendedFrames: 250,
-    description: "High-accuracy model - 250 frames, best accuracy"
+    description: "High-accuracy model - 250 frames, best accuracy",
+    deprecated: false
   },
   // Hybrid V2 models with physiological features
   "hybrid-v2-10": {
     type: "hybrid-v2-10",
     minFrames: 10,
     recommendedFrames: 10,
-    description: "Hybrid V2 10-frame model with physio features"
+    description: "Hybrid V2 10-frame model with physio features",
+    deprecated: false
   },
   "hybrid-v2-30": {
     type: "hybrid-v2-30",
     minFrames: 30,
     recommendedFrames: 30,
-    description: "Hybrid V2 30-frame model with physio features"
+    description: "Hybrid V2 30-frame model with physio features",
+    deprecated: false
   },
   "hybrid-v2-50": {
     type: "hybrid-v2-50",
     minFrames: 50,
     recommendedFrames: 50,
-    description: "Hybrid V2 50-frame model with physio features"
+    description: "Hybrid V2 50-frame model with physio features",
+    deprecated: false
   },
   "hybrid-v2-60": {
     type: "hybrid-v2-60",
     minFrames: 60,
     recommendedFrames: 60,
-    description: "Hybrid V2 60-frame model with physio features"
+    description: "Hybrid V2 60-frame model with physio features",
+    deprecated: false
   },
   "hybrid-v2-90": {
     type: "hybrid-v2-90",
     minFrames: 90,
     recommendedFrames: 90,
-    description: "Hybrid V2 90-frame model with physio features"
+    description: "Hybrid V2 90-frame model with physio features",
+    deprecated: false
   },
   "hybrid-v2-100": {
     type: "hybrid-v2-100",
     minFrames: 100,
     recommendedFrames: 100,
-    description: "Hybrid V2 100-frame model with physio features"
+    description: "Hybrid V2 100-frame model with physio features",
+    deprecated: false
   },
   "hybrid-v2-125": {
     type: "hybrid-v2-125",
     minFrames: 125,
     recommendedFrames: 125,
-    description: "Hybrid V2 125-frame model with physio features"
+    description: "Hybrid V2 125-frame model with physio features",
+    deprecated: false
   },
   "hybrid-v2-150": {
     type: "hybrid-v2-150",
     minFrames: 150,
     recommendedFrames: 150,
-    description: "Hybrid V2 150-frame model with physio features"
+    description: "Hybrid V2 150-frame model with physio features",
+    deprecated: false
   },
   "hybrid-v2-250": {
     type: "hybrid-v2-250",
     minFrames: 250,
     recommendedFrames: 250,
-    description: "Hybrid V2 250-frame model with physio features"
+    description: "Hybrid V2 250-frame model with physio features",
+    deprecated: false
   },
-  // Mixed models (FastLivenessDetector with mixed-trained weights)
+  // Mixed V1 models — deprecated, use mixed-*-v2 equivalents instead
   "mixed-10": {
     type: "mixed-10",
     minFrames: 10,
     recommendedFrames: 10,
-    description: "Mixed 10-frame model"
+    description: "Mixed 10-frame model",
+    deprecated: true
   },
   "mixed-30": {
     type: "mixed-30",
     minFrames: 30,
     recommendedFrames: 30,
-    description: "Mixed 30-frame model"
+    description: "Mixed 30-frame model",
+    deprecated: true
   },
   "mixed-60": {
     type: "mixed-60",
     minFrames: 60,
     recommendedFrames: 60,
-    description: "Mixed 60-frame model"
+    description: "Mixed 60-frame model",
+    deprecated: true
   },
   "mixed-90": {
     type: "mixed-90",
     minFrames: 90,
     recommendedFrames: 90,
-    description: "Mixed 90-frame model"
+    description: "Mixed 90-frame model",
+    deprecated: true
   },
   "mixed-120": {
     type: "mixed-120",
     minFrames: 120,
     recommendedFrames: 120,
-    description: "Mixed 120-frame model"
+    description: "Mixed 120-frame model",
+    deprecated: true
   },
   "mixed-150": {
     type: "mixed-150",
     minFrames: 150,
     recommendedFrames: 150,
-    description: "Mixed 150-frame model"
+    description: "Mixed 150-frame model",
+    deprecated: true
   },
   "mixed-250": {
     type: "mixed-250",
     minFrames: 250,
     recommendedFrames: 250,
-    description: "Mixed 250-frame model"
+    description: "Mixed 250-frame model",
+    deprecated: true
+  },
+  // Mixed V2 models (exp_042 checkpoints — EER: 4.0% / AUC: 0.991 at 30f)
+  "mixed-10-v2": {
+    type: "mixed-10-v2",
+    minFrames: 10,
+    recommendedFrames: 10,
+    description: "Mixed V2 10-frame model",
+    deprecated: false
+  },
+  "mixed-30-v2": {
+    type: "mixed-30-v2",
+    minFrames: 30,
+    recommendedFrames: 30,
+    description: "Mixed V2 30-frame model (recommended \u2014 95.7% balanced accuracy)",
+    deprecated: false
+  },
+  "mixed-60-v2": {
+    type: "mixed-60-v2",
+    minFrames: 60,
+    recommendedFrames: 60,
+    description: "Mixed V2 60-frame model",
+    deprecated: false
+  },
+  "mixed-90-v2": {
+    type: "mixed-90-v2",
+    minFrames: 90,
+    recommendedFrames: 90,
+    description: "Mixed V2 90-frame model",
+    deprecated: false
+  },
+  "mixed-120-v2": {
+    type: "mixed-120-v2",
+    minFrames: 120,
+    recommendedFrames: 120,
+    description: "Mixed V2 120-frame model",
+    deprecated: false
   }
 };
 var HYBRID_MODEL_CONFIGS = {
@@ -873,10 +937,16 @@ var HYBRID_MODEL_CONFIGS = {
   }
 };
 function getMinFramesForModel(model) {
-  return MODEL_CONFIGS[model].minFrames;
+  return MODEL_CONFIGS[model]?.minFrames ?? 10;
 }
 function hasEnoughFrames(model, frameCount) {
-  return frameCount >= MODEL_CONFIGS[model].minFrames;
+  return frameCount >= getMinFramesForModel(model);
+}
+function isDeprecatedModel(model) {
+  return MODEL_CONFIGS[model]?.deprecated ?? false;
+}
+function getActiveModels() {
+  return Object.values(MODEL_CONFIGS).filter((c) => !c.deprecated);
 }
 
 // src/types/detectors.ts
@@ -1043,6 +1113,12 @@ var FEEDBACK_MESSAGES = {
   backlit: "Backlit - try facing the light source",
   // Hand occlusion
   hand_detected: "Remove hand from face",
+  // Eye region quality
+  eyes_not_visible: "Eyes not clearly visible",
+  eyes_shadowed: "Eyes are in shadow - improve lighting",
+  eyes_overexposed: "Eye region overexposed - reduce lighting",
+  glasses_glare: "Glare detected - adjust angle or remove glasses",
+  eye_quality_poor: "Eye region quality is poor",
   // Progress messages
   capturing: "Capturing...",
   almost_done: "Almost done...",
@@ -1094,6 +1170,12 @@ var ES_LOCALE = {
     backlit: "Contraluz - intenta mirar hacia la fuente de luz",
     // Hand occlusion
     hand_detected: "Retira la mano del rostro",
+    // Eye region quality
+    eyes_not_visible: "Ojos no visibles claramente",
+    eyes_shadowed: "Ojos en sombra - mejora la iluminaci\xF3n",
+    eyes_overexposed: "Regi\xF3n de ojos sobreexpuesta - reduce la iluminaci\xF3n",
+    glasses_glare: "Reflejo detectado - ajusta el \xE1ngulo o retira los lentes",
+    eye_quality_poor: "Calidad de la regi\xF3n de ojos insuficiente",
     // Progress messages
     capturing: "Capturando...",
     almost_done: "Casi listo...",
@@ -1177,7 +1259,7 @@ function validateTimestamp(timestamp) {
 }
 function validateFrameCount(model, frameCount) {
   const config = MODEL_CONFIGS[model];
-  const required = config.minFrames;
+  const required = config?.minFrames ?? 10;
   return {
     valid: frameCount >= required,
     required,
@@ -1527,6 +1609,44 @@ var LANDMARK_INDEX = {
   /** Lower lip center */
   LOWER_LIP: 14
 };
+var EYE_LANDMARK_INDICES = {
+  /** Right eye contour (viewer's left) */
+  RIGHT_EYE: [33, 7, 163, 144, 145, 153, 154, 155, 133, 173, 157, 158, 159, 160, 161, 246],
+  /** Left eye contour (viewer's right) */
+  LEFT_EYE: [362, 382, 381, 380, 374, 373, 390, 249, 263, 466, 388, 387, 386, 385, 384, 398]
+};
+function getEyeRegionBounds(landmarks) {
+  if (landmarks.length < 468) return null;
+  const PADDING = 0.2;
+  function computeBounds(indices) {
+    let minX = 1;
+    let minY = 1;
+    let maxX = 0;
+    let maxY = 0;
+    for (const idx of indices) {
+      const lm = landmarks[idx];
+      if (!lm) continue;
+      if (lm.x < minX) minX = lm.x;
+      if (lm.y < minY) minY = lm.y;
+      if (lm.x > maxX) maxX = lm.x;
+      if (lm.y > maxY) maxY = lm.y;
+    }
+    const width = maxX - minX;
+    const height = maxY - minY;
+    const padX = width * PADDING;
+    const padY = height * PADDING;
+    return {
+      x: Math.max(0, minX - padX),
+      y: Math.max(0, minY - padY),
+      width: Math.min(1 - Math.max(0, minX - padX), width + padX * 2),
+      height: Math.min(1 - Math.max(0, minY - padY), height + padY * 2)
+    };
+  }
+  return {
+    rightEye: computeBounds(EYE_LANDMARK_INDICES.RIGHT_EYE),
+    leftEye: computeBounds(EYE_LANDMARK_INDICES.LEFT_EYE)
+  };
+}
 var LANDMARK_MIN_BOUND = 0.1;
 var LANDMARK_MAX_BOUND = 0.9;
 var MIN_LANDMARK_COUNT = 15;
@@ -1548,6 +1668,115 @@ function validateFaceLandmarks(landmarks) {
   }
   return { valid: true };
 }
+
+// src/utils/eyeRegionAnalysis.ts
+var EYE_QUALITY_THRESHOLDS = {
+  minBrightness: 40,
+  maxBrightness: 230,
+  minContrast: 12,
+  glarePixelThreshold: 240,
+  maxGlareRatio: 0.15
+};
+function rgbaToLuminance(r, g, b) {
+  return 0.299 * r + 0.587 * g + 0.114 * b;
+}
+function analyzeEyeRegionBrightness(pixels) {
+  const pixelCount = pixels.length / 4;
+  if (pixelCount === 0) return 0;
+  let totalLuminance = 0;
+  for (let i = 0; i < pixels.length; i += 4) {
+    totalLuminance += rgbaToLuminance(pixels[i], pixels[i + 1], pixels[i + 2]);
+  }
+  return totalLuminance / pixelCount;
+}
+function analyzeEyeRegionContrast(pixels, meanBrightness) {
+  const pixelCount = pixels.length / 4;
+  if (pixelCount === 0) return 0;
+  const mean = meanBrightness ?? analyzeEyeRegionBrightness(pixels);
+  let sumSqDiff = 0;
+  for (let i = 0; i < pixels.length; i += 4) {
+    const lum = rgbaToLuminance(pixels[i], pixels[i + 1], pixels[i + 2]);
+    const diff = lum - mean;
+    sumSqDiff += diff * diff;
+  }
+  return Math.sqrt(sumSqDiff / pixelCount);
+}
+function detectSpecularHighlights(pixels, threshold = EYE_QUALITY_THRESHOLDS.glarePixelThreshold) {
+  const pixelCount = pixels.length / 4;
+  if (pixelCount === 0) return 0;
+  let glareCount = 0;
+  for (let i = 0; i < pixels.length; i += 4) {
+    const lum = rgbaToLuminance(pixels[i], pixels[i + 1], pixels[i + 2]);
+    if (lum >= threshold) {
+      glareCount++;
+    }
+  }
+  return glareCount / pixelCount;
+}
+function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
+  if (pixels.length < 4) {
+    return {
+      passed: false,
+      brightness: 0,
+      contrast: 0,
+      hasGlare: false,
+      glareRatio: 0,
+      message: "Eyes not clearly visible"
+    };
+  }
+  const brightness = analyzeEyeRegionBrightness(pixels);
+  const contrast = analyzeEyeRegionContrast(pixels, brightness);
+  const glareRatio = detectSpecularHighlights(pixels, thresholds.glarePixelThreshold);
+  const hasGlare = glareRatio > thresholds.maxGlareRatio;
+  if (brightness < thresholds.minBrightness) {
+    return {
+      passed: false,
+      brightness,
+      contrast,
+      hasGlare,
+      glareRatio,
+      message: "Eyes are in shadow - improve lighting"
+    };
+  }
+  if (brightness > thresholds.maxBrightness) {
+    return {
+      passed: false,
+      brightness,
+      contrast,
+      hasGlare,
+      glareRatio,
+      message: "Eye region overexposed - reduce lighting"
+    };
+  }
+  if (hasGlare) {
+    return {
+      passed: false,
+      brightness,
+      contrast,
+      hasGlare,
+      glareRatio,
+      message: "Glare detected - adjust angle or remove glasses"
+    };
+  }
+  if (contrast < thresholds.minContrast) {
+    return {
+      passed: false,
+      brightness,
+      contrast,
+      hasGlare,
+      glareRatio,
+      message: "Eyes not clearly visible"
+    };
+  }
+  return {
+    passed: true,
+    brightness,
+    contrast,
+    hasGlare,
+    glareRatio,
+    message: null
+  };
+}
 export {
   ALIGNMENT_THRESHOLD_CAPTURE,
   ALIGNMENT_THRESHOLD_GOOD,
@@ -1573,6 +1802,8 @@ export {
   ERROR_MESSAGES,
   ERROR_MESSAGES_ES,
   ES_LOCALE,
+  EYE_LANDMARK_INDICES,
+  EYE_QUALITY_THRESHOLDS,
   FACE_CENTER_VERTICAL_OFFSET,
   FACE_CROP_OUTPUT_SIZE,
   FEEDBACK_MESSAGES,
@@ -1606,23 +1837,30 @@ export {
   RETRY_CONFIG,
   TARGET_FACE_PERCENTAGE_IN_CROP,
   analyzeBlur,
+  analyzeEyeRegionBrightness,
+  analyzeEyeRegionContrast,
   analyzeLighting,
   calculateAdaptiveCropMultiplier,
   calculateBrightness,
   calculateFaceAlignment,
   calculateFaceCropRegion,
   canCaptureFrame,
+  checkEyeRegionQuality,
   checkFrameQuality,
   decodeBase64,
+  detectSpecularHighlights,
   encodeBase64,
   generateSessionId,
+  getActiveModels,
   getApiErrorMessage,
   getCaptureQualityFeedback,
+  getEyeRegionBounds,
   getFeedbackMessage,
   getMinFramesForModel,
   getOvalGuideState,
   getStatusMessage,
   hasEnoughFrames,
+  isDeprecatedModel,
   isFaceCropFullyInFrame,
   isFaceFullyVisible,
   isFaceInOval,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moveris/shared",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Core business logic for Moveris Live SDK",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",