@moveris/shared 3.2.0 → 3.3.1

package/README.md

@@ -550,6 +550,7 @@ const status = getStatusMessage('capturing', DEFAULT_LOCALE);
 | `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         |
 
 ---
 
@@ -677,6 +678,13 @@ if (facialTransformationMatrix) {
 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;
@@ -750,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";
@@ -789,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;
@@ -839,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, detectFaceRollFromMatrix, 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;
@@ -750,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";
@@ -789,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;
@@ -839,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, detectFaceRollFromMatrix, 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,
@@ -119,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,
@@ -1294,6 +1298,10 @@ function getApiErrorMessage(code, message, customMessages) {
   if (code) {
     const custom = customMessages?.[code];
     if (custom) return custom;
+    if (code === API_ERROR_CODES.MISSING_FIELD && message && !looksLikeRawData(message)) {
+      const field = message.replace(" is required", "").trim();
+      if (field) return `Missing required field: ${field} \u2014 please try again`;
+    }
     const known = ERROR_MESSAGES[code];
     if (known) return known;
   }
@@ -1377,6 +1385,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",
@@ -1440,6 +1449,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",
@@ -1482,7 +1492,8 @@ function getCaptureQualityFeedback(state) {
     cameraAngleLow,
     cameraAngleHigh,
     cameraTilted,
-    faceAreaLow
+    faceAreaLow,
+    dynamicRangeLow
   } = state;
   if (!hasFace) {
     return FEEDBACK_MESSAGES.no_face;
@@ -1508,6 +1519,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;
   }
@@ -1632,6 +1646,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++) {
@@ -2180,6 +2221,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,
@@ -2225,6 +2267,7 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
   TARGET_FACE_PERCENTAGE_IN_CROP,
   VALID_FRAME_COUNTS,
   analyzeBlur,
+  analyzeDynamicRange,
   analyzeEyeRegionBrightness,
   analyzeEyeRegionContrast,
   analyzeLighting,
@@ -2256,9 +2299,11 @@ function checkEyeRegionQuality(pixels, thresholds = EYE_QUALITY_THRESHOLDS) {
   isFaceFullyVisible,
   isFaceInOval,
   isRetryableError,
+  linearRgbToLabL,
   retryWithBackoff,
   rgbaToGrayscale,
   sleep,
+  srgbToLinear,
   toFrameData,
   toHybridFrameData,
   toLivenessResult,

package/dist/index.mjs

@@ -1155,6 +1155,10 @@ function getApiErrorMessage(code, message, customMessages) {
   if (code) {
     const custom = customMessages?.[code];
     if (custom) return custom;
+    if (code === API_ERROR_CODES.MISSING_FIELD && message && !looksLikeRawData(message)) {
+      const field = message.replace(" is required", "").trim();
+      if (field) return `Missing required field: ${field} \u2014 please try again`;
+    }
     const known = ERROR_MESSAGES[code];
     if (known) return known;
   }
@@ -1238,6 +1242,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 +1306,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 +1349,8 @@ function getCaptureQualityFeedback(state) {
     cameraAngleLow,
     cameraAngleHigh,
     cameraTilted,
-    faceAreaLow
+    faceAreaLow,
+    dynamicRangeLow
   } = state;
   if (!hasFace) {
     return FEEDBACK_MESSAGES.no_face;
@@ -1369,6 +1376,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 +1503,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++) {
@@ -2040,6 +2077,7 @@ export {
   DEFAULT_OVAL_REGION,
   DEFAULT_STABILIZER_CONFIG,
   DEFAULT_STATUS_MESSAGES,
+  DYNAMIC_RANGE_WARNING_THRESHOLD,
   ERROR_MESSAGES,
   ERROR_MESSAGES_ES,
   ES_LOCALE,
@@ -2085,6 +2123,7 @@ export {
   TARGET_FACE_PERCENTAGE_IN_CROP,
   VALID_FRAME_COUNTS,
   analyzeBlur,
+  analyzeDynamicRange,
   analyzeEyeRegionBrightness,
   analyzeEyeRegionContrast,
   analyzeLighting,
@@ -2116,9 +2155,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.2.0",
+  "version": "3.3.1",
   "description": "Core business logic for Moveris Live SDK",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",