@moveris/shared 3.1.0 → 3.3.0

package/README.md

@@ -530,26 +530,27 @@ const status = getStatusMessage('capturing', DEFAULT_LOCALE);
 
 #### Feedback Keys
 
-| Key                 | English                        | Description                  |
-| ------------------- | ------------------------------ | ---------------------------- |
-| `no_face`           | "No face detected"             | Face detection failed        |
-| `face_not_centered` | "Center your face in the oval" | Face outside guide           |
-| `too_close`         | "Move back a little"           | Face too close to camera     |
-| `too_far`           | "Move closer"                  | Face too far from camera     |
-| `poor_lighting`     | "Improve lighting"             | Insufficient light           |
-| `hold_still`        | "Hold still"                   | Movement detected            |
-| `capturing`         | "Capturing..."                 | Frame capture in progress    |
-| `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  |
-| `camera_angle_low`  | "Raise camera to eye level"    | Camera below face (Y < 0.3)  |
-| `camera_angle_high` | "Lower camera to eye level"    | Camera above face (Y > 0.7)  |
-| `camera_tilted`     | "Hold camera level"            | Eye line deviates > 15°      |
+| Key                 | English                        | Description                                                                       |
+| ------------------- | ------------------------------ | --------------------------------------------------------------------------------- |
+| `no_face`           | "No face detected"             | Face detection failed                                                             |
+| `face_not_centered` | "Center your face in the oval" | Face outside guide                                                                |
+| `too_close`         | "Move back a little"           | Face too close to camera                                                          |
+| `too_far`           | "Move closer"                  | Face too far from camera                                                          |
+| `poor_lighting`     | "Improve lighting"             | Insufficient light                                                                |
+| `hold_still`        | "Hold still"                   | Movement detected                                                                 |
+| `capturing`         | "Capturing..."                 | Frame capture in progress                                                         |
+| `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                                                       |
+| `camera_angle_low`  | "Raise camera to eye level"    | Camera below face (Y < 0.3)                                                       |
+| `camera_angle_high` | "Lower camera to eye level"    | Camera above face (Y > 0.7)                                                       |
+| `camera_tilted`     | "Hold camera level"            | Device tilt > 15° (via transformation matrix, falls back to eye-corner landmarks) |
+| `flat_lighting`     | "Find better lighting"         | Face-region dynamic range < 180 L-units — soft warning, capture continues         |
 
 ---
 
@@ -641,6 +642,7 @@ import {
   isFaceInOval,
   calculateFaceCropRegion,
   detectFaceRoll,
+  detectFaceRollFromMatrix,
   detectCameraAngle,
 } from '@moveris/shared';
 
@@ -663,14 +665,26 @@ import { calculateAdaptiveCropMultiplier } from '@moveris/shared';
 const multiplier = calculateAdaptiveCropMultiplier(faceBox, frameWidth, frameHeight);
 // Returns 2.5–4.0x (matched to cognito-check for ~33% face coverage in 224×224 crop)
 
-// Detect face roll (device tilt) from eye-corner landmarks
-const rollResult = detectFaceRoll(landmarks); // requires ≥364 landmarks
-// { roll: number (degrees), tooTilted: boolean }
+// Detect face roll (device tilt) — prefer matrix when available (more accurate under glasses/occlusion)
+if (facialTransformationMatrix) {
+  const rollResult = detectFaceRollFromMatrix(facialTransformationMatrix); // 16-element column-major 4×4
+  // { roll: number (degrees), tooTilted: boolean }
+} else {
+  const rollResult = detectFaceRoll(landmarks); // fallback: eye-corner landmarks, requires ≥364 points
+  // { roll: number (degrees), tooTilted: boolean }
+}
 
 // Detect camera vertical angle from forehead/nose/chin landmark ratio
 const angleResult = detectCameraAngle(landmarks); // requires ≥153 landmarks
 // { ratio: number, cameraAbove: boolean, cameraBelow: boolean }
 // ratio ~1.0 at eye level; >1.35 = camera above user; <0.75 = camera below user
+
+// Analyse face-region dynamic range (flat lighting detection, MOV-1280)
+// Pass pre-sampled face-region pixels — use sampleFaceRegionPixels() in @moveris/react
+import { analyzeDynamicRange } from '@moveris/shared';
+const drResult = analyzeDynamicRange(rgbaPixels);
+// { range: number (max L* − min L*), isLow: boolean (< 180) }
+// Soft warning — do not use as a hard capture gate
 ```
 
 #### Crop Constants (aligned with cognito-check)

package/dist/index.d.mts

@@ -341,6 +341,14 @@ declare const MAX_FACE_RATIO = 0.7;
 declare const FACE_CROP_OUTPUT_SIZE = 224;
 declare const MAX_FACE_PERCENTAGE_IN_CROP = 0.45;
 declare const TARGET_FACE_PERCENTAGE_IN_CROP = 0.33;
+declare const DYNAMIC_RANGE_WARNING_THRESHOLD = 180;
+interface DynamicRangeAnalysis {
+    range: number;
+    isLow: boolean;
+}
+declare function srgbToLinear(c: number): number;
+declare function linearRgbToLabL(rLin: number, gLin: number, bLin: number): number;
+declare function analyzeDynamicRange(rgbaPixels: Uint8ClampedArray | number[]): DynamicRangeAnalysis;
 declare function analyzeBlur(grayscalePixels: number[], width: number, height: number, threshold?: number): BlurAnalysis;
 declare function rgbaToGrayscale(rgbaPixels: Uint8ClampedArray | number[]): number[];
 declare function calculateBrightness(rgbaPixels: Uint8ClampedArray | number[]): number;
@@ -372,6 +380,7 @@ interface FaceRollResult {
 }
 declare const MAX_FACE_ROLL_DEGREES = 15;
 declare function detectFaceRoll(landmarks: FaceLandmarkPoint[]): FaceRollResult;
+declare function detectFaceRollFromMatrix(matrix: number[]): FaceRollResult;
 interface CameraAngleResult {
     ratio: number;
     cameraAbove: boolean;
@@ -749,6 +758,7 @@ declare const FEEDBACK_MESSAGES: {
     readonly poor_lighting: "Improve lighting";
     readonly too_dark: "Low lighting - move to a brighter area";
     readonly backlit: "Backlit - try facing the light source";
+    readonly flat_lighting: "Find better lighting";
     readonly camera_angle_low: "Raise camera to eye level";
     readonly camera_angle_high: "Lower camera to eye level";
     readonly camera_tilted: "Hold camera level";
@@ -788,6 +798,7 @@ interface CaptureQualityState {
     cameraAngleHigh?: boolean;
     cameraTilted?: boolean;
     faceAreaLow?: boolean;
+    dynamicRangeLow?: boolean;
 }
 declare function getCaptureQualityFeedback(state: CaptureQualityState): string;
 declare function canCaptureFrame(state: Omit<CaptureQualityState, 'framesCaptured' | 'targetFrames' | 'isCapturing'>): boolean;
@@ -838,4 +849,4 @@ declare function analyzeEyeRegionContrast(pixels: Uint8Array | Uint8ClampedArray
 declare function detectSpecularHighlights(pixels: Uint8Array | Uint8ClampedArray, relativeFactor?: number, meanBrightness?: 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, CAMERA_ANGLE_HIGH_RATIO, CAMERA_ANGLE_LOW_RATIO, type CameraAngleResult, 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 DeprecationInfo, 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 FaceRollResult, 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, MAX_FACE_ROLL_DEGREES, MAX_IDEAL_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_CROP_MULTIPLIER, MIN_FACE_AREA_RATIO, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_IDEAL_FACE_RATIO, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelEntry, type ModelType, type ModelVersion, type ModelsResponse, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, OVAL_REGION_DESKTOP, OVAL_REGION_MOBILE, 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, VALID_FRAME_COUNTS, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeEyeRegionBrightness, analyzeEyeRegionContrast, analyzeLighting, calculateAdaptiveCropMultiplier, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkEyeRegionQuality, checkFrameQuality, decodeBase64, detectCameraAngle, detectFaceRoll, 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 };
+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, CAMERA_ANGLE_HIGH_RATIO, CAMERA_ANGLE_LOW_RATIO, type CameraAngleResult, 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, DYNAMIC_RANGE_WARNING_THRESHOLD, type DeprecationInfo, type DetectionResult, type DetectionSummary, type DetectorConfig, type DynamicRangeAnalysis, 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 FaceRollResult, 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, MAX_FACE_ROLL_DEGREES, MAX_IDEAL_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_CROP_MULTIPLIER, MIN_FACE_AREA_RATIO, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_IDEAL_FACE_RATIO, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelEntry, type ModelType, type ModelVersion, type ModelsResponse, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, OVAL_REGION_DESKTOP, OVAL_REGION_MOBILE, 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, VALID_FRAME_COUNTS, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeDynamicRange, analyzeEyeRegionBrightness, analyzeEyeRegionContrast, analyzeLighting, calculateAdaptiveCropMultiplier, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkEyeRegionQuality, checkFrameQuality, decodeBase64, detectCameraAngle, detectFaceRoll, detectFaceRollFromMatrix, detectSpecularHighlights, encodeBase64, generateSessionId, getActiveModels, getApiErrorMessage, getCaptureQualityFeedback, getEyeRegionBounds, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isDeprecatedModel, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, linearRgbToLabL, retryWithBackoff, rgbaToGrayscale, sleep, srgbToLinear, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };

package/dist/index.d.ts

@@ -341,6 +341,14 @@ declare const MAX_FACE_RATIO = 0.7;
 declare const FACE_CROP_OUTPUT_SIZE = 224;
 declare const MAX_FACE_PERCENTAGE_IN_CROP = 0.45;
 declare const TARGET_FACE_PERCENTAGE_IN_CROP = 0.33;
+declare const DYNAMIC_RANGE_WARNING_THRESHOLD = 180;
+interface DynamicRangeAnalysis {
+    range: number;
+    isLow: boolean;
+}
+declare function srgbToLinear(c: number): number;
+declare function linearRgbToLabL(rLin: number, gLin: number, bLin: number): number;
+declare function analyzeDynamicRange(rgbaPixels: Uint8ClampedArray | number[]): DynamicRangeAnalysis;
 declare function analyzeBlur(grayscalePixels: number[], width: number, height: number, threshold?: number): BlurAnalysis;
 declare function rgbaToGrayscale(rgbaPixels: Uint8ClampedArray | number[]): number[];
 declare function calculateBrightness(rgbaPixels: Uint8ClampedArray | number[]): number;
@@ -372,6 +380,7 @@ interface FaceRollResult {
 }
 declare const MAX_FACE_ROLL_DEGREES = 15;
 declare function detectFaceRoll(landmarks: FaceLandmarkPoint[]): FaceRollResult;
+declare function detectFaceRollFromMatrix(matrix: number[]): FaceRollResult;
 interface CameraAngleResult {
     ratio: number;
     cameraAbove: boolean;
@@ -749,6 +758,7 @@ declare const FEEDBACK_MESSAGES: {
     readonly poor_lighting: "Improve lighting";
     readonly too_dark: "Low lighting - move to a brighter area";
     readonly backlit: "Backlit - try facing the light source";
+    readonly flat_lighting: "Find better lighting";
     readonly camera_angle_low: "Raise camera to eye level";
     readonly camera_angle_high: "Lower camera to eye level";
     readonly camera_tilted: "Hold camera level";
@@ -788,6 +798,7 @@ interface CaptureQualityState {
     cameraAngleHigh?: boolean;
     cameraTilted?: boolean;
     faceAreaLow?: boolean;
+    dynamicRangeLow?: boolean;
 }
 declare function getCaptureQualityFeedback(state: CaptureQualityState): string;
 declare function canCaptureFrame(state: Omit<CaptureQualityState, 'framesCaptured' | 'targetFrames' | 'isCapturing'>): boolean;
@@ -838,4 +849,4 @@ declare function analyzeEyeRegionContrast(pixels: Uint8Array | Uint8ClampedArray
 declare function detectSpecularHighlights(pixels: Uint8Array | Uint8ClampedArray, relativeFactor?: number, meanBrightness?: 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, CAMERA_ANGLE_HIGH_RATIO, CAMERA_ANGLE_LOW_RATIO, type CameraAngleResult, 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 DeprecationInfo, 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 FaceRollResult, 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, MAX_FACE_ROLL_DEGREES, MAX_IDEAL_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_CROP_MULTIPLIER, MIN_FACE_AREA_RATIO, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_IDEAL_FACE_RATIO, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelEntry, type ModelType, type ModelVersion, type ModelsResponse, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, OVAL_REGION_DESKTOP, OVAL_REGION_MOBILE, 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, VALID_FRAME_COUNTS, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeEyeRegionBrightness, analyzeEyeRegionContrast, analyzeLighting, calculateAdaptiveCropMultiplier, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkEyeRegionQuality, checkFrameQuality, decodeBase64, detectCameraAngle, detectFaceRoll, 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 };
+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, CAMERA_ANGLE_HIGH_RATIO, CAMERA_ANGLE_LOW_RATIO, type CameraAngleResult, 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, DYNAMIC_RANGE_WARNING_THRESHOLD, type DeprecationInfo, type DetectionResult, type DetectionSummary, type DetectorConfig, type DynamicRangeAnalysis, 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 FaceRollResult, 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, MAX_FACE_ROLL_DEGREES, MAX_IDEAL_FACE_RATIO, MIN_CAPTURE_ALIGNMENT, MIN_CROP_MULTIPLIER, MIN_FACE_AREA_RATIO, MIN_FACE_BOTTOM_MARGIN, MIN_FACE_RATIO, MIN_FACE_SIDE_MARGIN, MIN_FACE_TOP_MARGIN, MIN_IDEAL_FACE_RATIO, MIN_LANDMARK_COUNT, MODEL_CONFIGS, type ModelConfig, type ModelEntry, type ModelType, type ModelVersion, type ModelsResponse, OVAL_GUIDE_COLORS, OVAL_GUIDE_STYLES, OVAL_REGION_DESKTOP, OVAL_REGION_MOBILE, 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, VALID_FRAME_COUNTS, type Verdict, type VerifyRequest, type VerifyResponse, type VideoFrameMetadata, analyzeBlur, analyzeDynamicRange, analyzeEyeRegionBrightness, analyzeEyeRegionContrast, analyzeLighting, calculateAdaptiveCropMultiplier, calculateBrightness, calculateFaceAlignment, calculateFaceCropRegion, canCaptureFrame, checkEyeRegionQuality, checkFrameQuality, decodeBase64, detectCameraAngle, detectFaceRoll, detectFaceRollFromMatrix, detectSpecularHighlights, encodeBase64, generateSessionId, getActiveModels, getApiErrorMessage, getCaptureQualityFeedback, getEyeRegionBounds, getFeedbackMessage, getMinFramesForModel, getOvalGuideState, getStatusMessage, hasEnoughFrames, isDeprecatedModel, isFaceCropFullyInFrame, isFaceFullyVisible, isFaceInOval, isRetryableError, linearRgbToLabL, retryWithBackoff, rgbaToGrayscale, sleep, srgbToLinear, toFrameData, toHybridFrameData, toLivenessResult, toLivenessResultFromStream, validateApiKey, validateFaceLandmarks, validateFrameCount, validateFrameData, validateFrameIndex, validateTimestamp, validateUUID, validateUrl };

package/dist/index.js

@@ -43,6 +43,7 @@ __export(index_exports, {
   DEFAULT_OVAL_REGION: () => DEFAULT_OVAL_REGION,
   DEFAULT_STABILIZER_CONFIG: () => DEFAULT_STABILIZER_CONFIG,
   DEFAULT_STATUS_MESSAGES: () => DEFAULT_STATUS_MESSAGES,
+  DYNAMIC_RANGE_WARNING_THRESHOLD: () => DYNAMIC_RANGE_WARNING_THRESHOLD,
   ERROR_MESSAGES: () => ERROR_MESSAGES,
   ERROR_MESSAGES_ES: () => ERROR_MESSAGES_ES,
   ES_LOCALE: () => ES_LOCALE,
@@ -88,6 +89,7 @@ __export(index_exports, {
   TARGET_FACE_PERCENTAGE_IN_CROP: () => TARGET_FACE_PERCENTAGE_IN_CROP,
   VALID_FRAME_COUNTS: () => VALID_FRAME_COUNTS,
   analyzeBlur: () => analyzeBlur,
+  analyzeDynamicRange: () => analyzeDynamicRange,
   analyzeEyeRegionBrightness: () => analyzeEyeRegionBrightness,
   analyzeEyeRegionContrast: () => analyzeEyeRegionContrast,
   analyzeLighting: () => analyzeLighting,
@@ -101,6 +103,7 @@ __export(index_exports, {
   decodeBase64: () => decodeBase64,
   detectCameraAngle: () => detectCameraAngle,
   detectFaceRoll: () => detectFaceRoll,
+  detectFaceRollFromMatrix: () => detectFaceRollFromMatrix,
   detectSpecularHighlights: () => detectSpecularHighlights,
   encodeBase64: () => encodeBase64,
   generateSessionId: () => generateSessionId,
@@ -118,9 +121,11 @@ __export(index_exports, {
   isFaceFullyVisible: () => isFaceFullyVisible,
   isFaceInOval: () => isFaceInOval,
   isRetryableError: () => isRetryableError,
+  linearRgbToLabL: () => linearRgbToLabL,
   retryWithBackoff: () => retryWithBackoff,
   rgbaToGrayscale: () => rgbaToGrayscale,
   sleep: () => sleep,
+  srgbToLinear: () => srgbToLinear,
   toFrameData: () => toFrameData,
   toHybridFrameData: () => toHybridFrameData,
   toLivenessResult: () => toLivenessResult,
@@ -1376,6 +1381,7 @@ var FEEDBACK_MESSAGES = {
   poor_lighting: "Improve lighting",
   too_dark: "Low lighting - move to a brighter area",
   backlit: "Backlit - try facing the light source",
+  flat_lighting: "Find better lighting",
   // Camera angle (platform-agnostic)
   camera_angle_low: "Raise camera to eye level",
   camera_angle_high: "Lower camera to eye level",
@@ -1439,6 +1445,7 @@ var ES_LOCALE = {
     poor_lighting: "Mejora la iluminaci\xF3n",
     too_dark: "Poca luz - mu\xE9vete a un \xE1rea m\xE1s iluminada",
     backlit: "Contraluz - intenta mirar hacia la fuente de luz",
+    flat_lighting: "Busca mejor iluminaci\xF3n",
     // Camera angle (platform-agnostic)
     camera_angle_low: "Levanta la c\xE1mara a la altura de los ojos",
     camera_angle_high: "Baja la c\xE1mara a la altura de los ojos",
@@ -1481,7 +1488,8 @@ function getCaptureQualityFeedback(state) {
     cameraAngleLow,
     cameraAngleHigh,
     cameraTilted,
-    faceAreaLow
+    faceAreaLow,
+    dynamicRangeLow
   } = state;
   if (!hasFace) {
     return FEEDBACK_MESSAGES.no_face;
@@ -1507,6 +1515,9 @@ function getCaptureQualityFeedback(state) {
   if (isBlurry) {
     return FEEDBACK_MESSAGES.blurry;
   }
+  if (dynamicRangeLow) {
+    return FEEDBACK_MESSAGES.flat_lighting;
+  }
   if (tooFarFromIdeal) {
     return FEEDBACK_MESSAGES.move_closer_ideal;
   }
@@ -1631,6 +1642,33 @@ var MAX_FACE_RATIO = 0.7;
 var FACE_CROP_OUTPUT_SIZE = 224;
 var MAX_FACE_PERCENTAGE_IN_CROP = 0.45;
 var TARGET_FACE_PERCENTAGE_IN_CROP = 0.33;
+var DYNAMIC_RANGE_WARNING_THRESHOLD = 180;
+function srgbToLinear(c) {
+  const n = c / 255;
+  return n <= 0.04045 ? n / 12.92 : Math.pow((n + 0.055) / 1.055, 2.4);
+}
+function linearRgbToLabL(rLin, gLin, bLin) {
+  const Y = 0.2126 * rLin + 0.7152 * gLin + 0.0722 * bLin;
+  const f = Y > 8856e-6 ? Math.cbrt(Y) : 7.787 * Y + 16 / 116;
+  return 116 * f - 16;
+}
+function analyzeDynamicRange(rgbaPixels) {
+  let minL = Infinity;
+  let maxL = -Infinity;
+  for (let i = 0; i < rgbaPixels.length; i += 4) {
+    const r = rgbaPixels[i] ?? 0;
+    const g = rgbaPixels[i + 1] ?? 0;
+    const b = rgbaPixels[i + 2] ?? 0;
+    const L = linearRgbToLabL(srgbToLinear(r), srgbToLinear(g), srgbToLinear(b));
+    if (L < minL) minL = L;
+    if (L > maxL) maxL = L;
+  }
+  if (!isFinite(minL) || !isFinite(maxL)) {
+    return { range: 0, isLow: false };
+  }
+  const range = maxL - minL;
+  return { range, isLow: range < DYNAMIC_RANGE_WARNING_THRESHOLD };
+}
 function analyzeBlur(grayscalePixels, width, height, threshold = DEFAULT_BLUR_THRESHOLD) {
   const laplacian = [];
   for (let y = 1; y < height - 1; y++) {
@@ -1911,6 +1949,21 @@ function detectFaceRoll(landmarks) {
     tooTilted: roll > MAX_FACE_ROLL_DEGREES
   };
 }
+function detectFaceRollFromMatrix(matrix) {
+  if (matrix.length < 9) {
+    return { roll: 0, tooTilted: false };
+  }
+  const m4 = matrix[4];
+  const m5 = matrix[5];
+  if (m4 === void 0 || m5 === void 0) {
+    return { roll: 0, tooTilted: false };
+  }
+  const roll = Math.abs(Math.atan2(m4, m5) * (180 / Math.PI));
+  return {
+    roll,
+    tooTilted: roll > MAX_FACE_ROLL_DEGREES
+  };
+}
 var CAMERA_ANGLE_HIGH_RATIO = 1.35;
 var CAMERA_ANGLE_LOW_RATIO = 0.75;
 function detectCameraAngle(landmarks) {
@@ -2164,6 +2217,7 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
   DEFAULT_OVAL_REGION,
   DEFAULT_STABILIZER_CONFIG,
   DEFAULT_STATUS_MESSAGES,
+  DYNAMIC_RANGE_WARNING_THRESHOLD,
   ERROR_MESSAGES,
   ERROR_MESSAGES_ES,
   ES_LOCALE,
@@ -2209,6 +2263,7 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
   TARGET_FACE_PERCENTAGE_IN_CROP,
   VALID_FRAME_COUNTS,
   analyzeBlur,
+  analyzeDynamicRange,
   analyzeEyeRegionBrightness,
   analyzeEyeRegionContrast,
   analyzeLighting,
@@ -2222,6 +2277,7 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
   decodeBase64,
   detectCameraAngle,
   detectFaceRoll,
+  detectFaceRollFromMatrix,
   detectSpecularHighlights,
   encodeBase64,
   generateSessionId,
@@ -2239,9 +2295,11 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
   isFaceFullyVisible,
   isFaceInOval,
   isRetryableError,
+  linearRgbToLabL,
   retryWithBackoff,
   rgbaToGrayscale,
   sleep,
+  srgbToLinear,
   toFrameData,
   toHybridFrameData,
   toLivenessResult,

package/dist/index.mjs

@@ -1238,6 +1238,7 @@ var FEEDBACK_MESSAGES = {
   poor_lighting: "Improve lighting",
   too_dark: "Low lighting - move to a brighter area",
   backlit: "Backlit - try facing the light source",
+  flat_lighting: "Find better lighting",
   // Camera angle (platform-agnostic)
   camera_angle_low: "Raise camera to eye level",
   camera_angle_high: "Lower camera to eye level",
@@ -1301,6 +1302,7 @@ var ES_LOCALE = {
     poor_lighting: "Mejora la iluminaci\xF3n",
     too_dark: "Poca luz - mu\xE9vete a un \xE1rea m\xE1s iluminada",
     backlit: "Contraluz - intenta mirar hacia la fuente de luz",
+    flat_lighting: "Busca mejor iluminaci\xF3n",
     // Camera angle (platform-agnostic)
     camera_angle_low: "Levanta la c\xE1mara a la altura de los ojos",
     camera_angle_high: "Baja la c\xE1mara a la altura de los ojos",
@@ -1343,7 +1345,8 @@ function getCaptureQualityFeedback(state) {
     cameraAngleLow,
     cameraAngleHigh,
     cameraTilted,
-    faceAreaLow
+    faceAreaLow,
+    dynamicRangeLow
   } = state;
   if (!hasFace) {
     return FEEDBACK_MESSAGES.no_face;
@@ -1369,6 +1372,9 @@ function getCaptureQualityFeedback(state) {
   if (isBlurry) {
     return FEEDBACK_MESSAGES.blurry;
   }
+  if (dynamicRangeLow) {
+    return FEEDBACK_MESSAGES.flat_lighting;
+  }
   if (tooFarFromIdeal) {
     return FEEDBACK_MESSAGES.move_closer_ideal;
   }
@@ -1493,6 +1499,33 @@ var MAX_FACE_RATIO = 0.7;
 var FACE_CROP_OUTPUT_SIZE = 224;
 var MAX_FACE_PERCENTAGE_IN_CROP = 0.45;
 var TARGET_FACE_PERCENTAGE_IN_CROP = 0.33;
+var DYNAMIC_RANGE_WARNING_THRESHOLD = 180;
+function srgbToLinear(c) {
+  const n = c / 255;
+  return n <= 0.04045 ? n / 12.92 : Math.pow((n + 0.055) / 1.055, 2.4);
+}
+function linearRgbToLabL(rLin, gLin, bLin) {
+  const Y = 0.2126 * rLin + 0.7152 * gLin + 0.0722 * bLin;
+  const f = Y > 8856e-6 ? Math.cbrt(Y) : 7.787 * Y + 16 / 116;
+  return 116 * f - 16;
+}
+function analyzeDynamicRange(rgbaPixels) {
+  let minL = Infinity;
+  let maxL = -Infinity;
+  for (let i = 0; i < rgbaPixels.length; i += 4) {
+    const r = rgbaPixels[i] ?? 0;
+    const g = rgbaPixels[i + 1] ?? 0;
+    const b = rgbaPixels[i + 2] ?? 0;
+    const L = linearRgbToLabL(srgbToLinear(r), srgbToLinear(g), srgbToLinear(b));
+    if (L < minL) minL = L;
+    if (L > maxL) maxL = L;
+  }
+  if (!isFinite(minL) || !isFinite(maxL)) {
+    return { range: 0, isLow: false };
+  }
+  const range = maxL - minL;
+  return { range, isLow: range < DYNAMIC_RANGE_WARNING_THRESHOLD };
+}
 function analyzeBlur(grayscalePixels, width, height, threshold = DEFAULT_BLUR_THRESHOLD) {
   const laplacian = [];
   for (let y = 1; y < height - 1; y++) {
@@ -1773,6 +1806,21 @@ function detectFaceRoll(landmarks) {
     tooTilted: roll > MAX_FACE_ROLL_DEGREES
   };
 }
+function detectFaceRollFromMatrix(matrix) {
+  if (matrix.length < 9) {
+    return { roll: 0, tooTilted: false };
+  }
+  const m4 = matrix[4];
+  const m5 = matrix[5];
+  if (m4 === void 0 || m5 === void 0) {
+    return { roll: 0, tooTilted: false };
+  }
+  const roll = Math.abs(Math.atan2(m4, m5) * (180 / Math.PI));
+  return {
+    roll,
+    tooTilted: roll > MAX_FACE_ROLL_DEGREES
+  };
+}
 var CAMERA_ANGLE_HIGH_RATIO = 1.35;
 var CAMERA_ANGLE_LOW_RATIO = 0.75;
 function detectCameraAngle(landmarks) {
@@ -2025,6 +2073,7 @@ export {
   DEFAULT_OVAL_REGION,
   DEFAULT_STABILIZER_CONFIG,
   DEFAULT_STATUS_MESSAGES,
+  DYNAMIC_RANGE_WARNING_THRESHOLD,
   ERROR_MESSAGES,
   ERROR_MESSAGES_ES,
   ES_LOCALE,
@@ -2070,6 +2119,7 @@ export {
   TARGET_FACE_PERCENTAGE_IN_CROP,
   VALID_FRAME_COUNTS,
   analyzeBlur,
+  analyzeDynamicRange,
   analyzeEyeRegionBrightness,
   analyzeEyeRegionContrast,
   analyzeLighting,
@@ -2083,6 +2133,7 @@ export {
   decodeBase64,
   detectCameraAngle,
   detectFaceRoll,
+  detectFaceRollFromMatrix,
   detectSpecularHighlights,
   encodeBase64,
   generateSessionId,
@@ -2100,9 +2151,11 @@ export {
   isFaceFullyVisible,
   isFaceInOval,
   isRetryableError,
+  linearRgbToLabL,
   retryWithBackoff,
   rgbaToGrayscale,
   sleep,
+  srgbToLinear,
   toFrameData,
   toHybridFrameData,
   toLivenessResult,

package/package.json

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