scandoc-ai-components 0.1.17 → 0.1.19

package/dist/index.js

@@ -11174,16 +11174,6 @@ class ExtractorVideo {
   static VALIDATION_BATCH_SIZE = 1;
   static VALIDATION_IMG_WIDTH = 384;
   static VALIDATION_IMG_HEIGHT = 384;
-  static VIDEO_CANDIDATE_SETTINGS = Object.freeze([{
-    width: 1920,
-    height: 1080
-  }, {
-    width: 1280,
-    height: 960
-  }, {
-    width: 1280,
-    height: 720
-  }]);
   constructor(onExtractedResults) {
     this.candidateImages = [];
     this.extractionImages = {};
@@ -11197,7 +11187,8 @@ class ExtractorVideo {
     this.waitingForSecondSide = false;
     this.hasShownTurnMessage = false;
     this.turnMessageTimer = null;
-    this.onExtractedResults = onExtractedResults;
+    this.currentStream = null;
+    this.lastCameraInfo = null;
   }
   reset() {
     this.stopVideo();
@@ -11213,6 +11204,7 @@ class ExtractorVideo {
     this.lastMessage = null;
     this.waitingForSecondSide = false;
     this.hasShownTurnMessage = false;
+    this.lastCameraInfo = null;
     clearTimeout(this.turnMessageTimer);
     this.turnMessageTimer = null;
   }
@@ -11365,7 +11357,7 @@ class ExtractorVideo {
     this.turnMessageTimer = null;
     this.stopVideo();
     if (isExtractionOk) {
-      this.showMessage("Success - data extracted", "success");
+      this.showMessage("Success - data extracted", true);
       const shouldStop = this.onExtractedResults({
         success: true,
         code: "001",
@@ -11373,7 +11365,7 @@ class ExtractorVideo {
         data: extractionData
       });
       if (shouldStop === true) {
-        setTimeout(() => this.analyzeVideoStream(), ExtractorVideo.FREQUENCY_MS);
+        setTimeout(() => this.startVideo(), ExtractorVideo.FREQUENCY_MS);
       }
     } else {
       this.onExtractedResults({
@@ -11381,378 +11373,8 @@ class ExtractorVideo {
         code: "005",
         info: "Document validation passed but extraction failed."
       });
-      setTimeout(() => this.analyzeVideoStream(), ExtractorVideo.FREQUENCY_MS);
-    }
-  }
-  getSupportedConstraintsSafe() {
-    if (!navigator.mediaDevices?.getSupportedConstraints) return {};
-    try {
-      return navigator.mediaDevices.getSupportedConstraints();
-    } catch (_) {
-      return {};
-    }
-  }
-  getAspectRatio(settings) {
-    if (typeof settings?.aspectRatio === "number" && settings.aspectRatio > 0) {
-      return settings.aspectRatio;
-    }
-    if (settings?.width && settings?.height) {
-      return settings.width / settings.height;
-    }
-    return null;
-  }
-  isLandscape(settings) {
-    return (settings?.width || 0) > (settings?.height || 0);
-  }
-  isFrontLabel(label) {
-    const l = (label || "").toLowerCase();
-    return l.includes("front") || l.includes("selfie") || l.includes("user facing") || l.includes("facing front");
-  }
-  isRearLikeLabel(label) {
-    const l = (label || "").toLowerCase();
-    return l.includes("rear") || l.includes("back") || l.includes("environment") || l.includes("facing back") || l.includes("facing rear");
-  }
-  scoreTrack({
-    settings,
-    label
-  }) {
-    const width = settings?.width || 0;
-    const height = settings?.height || 0;
-    const pixels = width * height;
-    const aspectRatio = this.getAspectRatio(settings) || 0;
-    let score = pixels;
-    if (width > height) score += 1_000_000_000;
-    if (aspectRatio >= 1.3) score += 100_000_000;
-    if (this.isRearLikeLabel(label)) score += 10_000_000;
-    if (this.isFrontLabel(label)) score -= 10_000_000_000;
-    return score;
-  }
-  buildVideoConstraints({
-    width,
-    height,
-    mode,
-    deviceId
-  }) {
-    const supported = this.getSupportedConstraintsSafe();
-    const video = {};
-    if (deviceId) {
-      video.deviceId = {
-        exact: deviceId
-      };
-    } else if (supported.facingMode) {
-      if (typeof mode === "string") {
-        video.facingMode = {
-          ideal: mode
-        };
-      } else if (mode && typeof mode === "object") {
-        video.facingMode = mode;
-      } else {
-        video.facingMode = {
-          ideal: "environment"
-        };
-      }
-    }
-    if (supported.width) {
-      video.width = {
-        ideal: width
-      };
-    }
-    if (supported.height) {
-      video.height = {
-        ideal: height
-      };
-    }
-    if (supported.aspectRatio) {
-      video.aspectRatio = {
-        ideal: width / height
-      };
-    }
-    return {
-      video,
-      audio: false
-    };
-  }
-  async pauseBetweenCameraOps(ms = 180) {
-    await new Promise(resolve => setTimeout(resolve, ms));
-  }
-  async stopMediaStream(stream) {
-    if (!stream) return;
-    try {
-      stream.getTracks().forEach(t => t.stop());
-    } catch (_) {}
-    await this.pauseBetweenCameraOps();
-  }
-  async tryEnableDocumentFocus(stream) {
-    const track = stream?.getVideoTracks?.()[0];
-    if (!track) {
-      return {
-        ok: false,
-        reason: "No video track found"
-      };
-    }
-    if (!track.getCapabilities || !track.applyConstraints) {
-      return {
-        ok: false,
-        reason: "Focus APIs unavailable on this browser/device",
-        settingsBefore: track.getSettings ? track.getSettings() : null
-      };
-    }
-    const caps = track.getCapabilities();
-    const result = {
-      ok: true,
-      capabilities: caps,
-      attempts: [],
-      settingsBefore: track.getSettings ? track.getSettings() : null
-    };
-    try {
-      let applied = false;
-      if (Array.isArray(caps.focusMode) && caps.focusMode.includes("continuous")) {
-        await track.applyConstraints({
-          advanced: [{
-            focusMode: "continuous"
-          }]
-        });
-        result.attempts.push("Applied focusMode=continuous");
-        applied = true;
-      }
-      if (caps.focusDistance) {
-        const min = caps.focusDistance.min;
-        const max = caps.focusDistance.max;
-        const docDistance = min + (max - min) * 0.30;
-        const advanced = [];
-        if (Array.isArray(caps.focusMode) && caps.focusMode.includes("manual")) {
-          advanced.push({
-            focusMode: "manual"
-          });
-        }
-        advanced.push({
-          focusDistance: docDistance
-        });
-        await track.applyConstraints({
-          advanced
-        });
-        result.attempts.push(`Applied focusDistance=${docDistance}`);
-        applied = true;
-      }
-      if (!applied) {
-        result.ok = false;
-        result.reason = "No supported focus controls were exposed";
-      }
-      result.settingsAfter = track.getSettings ? track.getSettings() : null;
-      return result;
-    } catch (err) {
-      result.ok = false;
-      result.error = err.message || String(err);
-      result.settingsAfter = track.getSettings ? track.getSettings() : null;
-      return result;
-    }
-  }
-  async openCandidateStream({
-    mode,
-    deviceId,
-    width,
-    height
-  }) {
-    return navigator.mediaDevices.getUserMedia(this.buildVideoConstraints({
-      width,
-      height,
-      mode,
-      deviceId
-    }));
-  }
-  async testDeviceAtPreferredResolutions(device, mode) {
-    const attempts = [];
-    for (const size of ExtractorVideo.VIDEO_CANDIDATE_SETTINGS) {
-      let stream = null;
-      try {
-        stream = await this.openCandidateStream({
-          mode,
-          deviceId: device?.deviceId,
-          width: size.width,
-          height: size.height
-        });
-        const track = stream.getVideoTracks()[0];
-        const settings = track.getSettings();
-        const label = track.label || device?.label || "";
-        const aspectRatio = this.getAspectRatio(settings);
-        const result = {
-          stream,
-          label,
-          settings,
-          aspectRatio,
-          landscape: this.isLandscape(settings),
-          score: this.scoreTrack({
-            settings,
-            label
-          }),
-          requested: size
-        };
-        attempts.push({
-          ok: true,
-          requested: size,
-          returnedWidth: settings.width,
-          returnedHeight: settings.height,
-          aspectRatio,
-          label
-        });
-        return {
-          result,
-          attempts
-        };
-      } catch (err) {
-        attempts.push({
-          ok: false,
-          requested: size,
-          error: err.message || String(err)
-        });
-        await this.stopMediaStream(stream);
-      }
+      setTimeout(() => this.startVideo(), ExtractorVideo.FREQUENCY_MS);
     }
-    return {
-      result: null,
-      attempts
-    };
-  }
-  async pickBestPhoneCamera(mode = "environment") {
-    const debug = {
-      mode,
-      tested: []
-    };
-
-    // First try a warmup stream to unlock labels
-    let warmupStream = null;
-    let warmupResult = null;
-    try {
-      const warmupSize = ExtractorVideo.VIDEO_CANDIDATE_SETTINGS[2]; // 1280x720
-      warmupStream = await this.openCandidateStream({
-        mode,
-        width: warmupSize.width,
-        height: warmupSize.height
-      });
-      const track = warmupStream.getVideoTracks()[0];
-      const settings = track.getSettings();
-      const label = track.label || "";
-      warmupResult = {
-        stream: warmupStream,
-        label,
-        settings,
-        aspectRatio: this.getAspectRatio(settings),
-        landscape: this.isLandscape(settings),
-        score: this.scoreTrack({
-          settings,
-          label
-        }),
-        requested: warmupSize
-      };
-    } catch (_) {
-      warmupStream = null;
-    }
-    let devices = [];
-    try {
-      devices = await navigator.mediaDevices.enumerateDevices();
-    } catch (_) {
-      devices = [];
-    }
-    const videoInputs = devices.filter(d => d.kind === "videoinput");
-    const candidateDevices = mode === "environment" ? videoInputs.filter(d => !this.isFrontLabel(d.label)) : videoInputs;
-    if (warmupStream) {
-      await this.stopMediaStream(warmupStream);
-      warmupStream = null;
-    }
-    const usableResults = [];
-    for (let i = 0; i < candidateDevices.length; i += 1) {
-      const device = candidateDevices[i];
-      const {
-        result,
-        attempts
-      } = await this.testDeviceAtPreferredResolutions(device, mode);
-      debug.tested.push({
-        deviceId: device.deviceId,
-        label: device.label,
-        attempts,
-        final: result ? {
-          label: result.label,
-          settings: result.settings,
-          aspectRatio: result.aspectRatio,
-          landscape: result.landscape,
-          score: result.score,
-          requested: result.requested
-        } : null
-      });
-      if (result) {
-        const frontRejected = mode === "environment" && this.isFrontLabel(result.label);
-        const geometryOk = result.landscape;
-        if (!frontRejected && geometryOk) {
-          usableResults.push(result);
-        } else {
-          await this.stopMediaStream(result.stream);
-        }
-      }
-    }
-    if (usableResults.length > 0) {
-      usableResults.sort((a, b) => b.score - a.score);
-      const chosen = usableResults[0];
-      for (const candidate of usableResults) {
-        if (candidate !== chosen) {
-          await this.stopMediaStream(candidate.stream);
-        }
-      }
-      debug.chosen = {
-        label: chosen.label,
-        settings: chosen.settings,
-        aspectRatio: chosen.aspectRatio,
-        requested: chosen.requested,
-        source: "device-test"
-      };
-      return {
-        chosen,
-        debug
-      };
-    }
-
-    // Final fallback: simple facingMode-based opens in descending priority
-    for (const size of ExtractorVideo.VIDEO_CANDIDATE_SETTINGS) {
-      try {
-        const stream = await this.openCandidateStream({
-          mode,
-          width: size.width,
-          height: size.height
-        });
-        const track = stream.getVideoTracks()[0];
-        const settings = track.getSettings();
-        const label = track.label || "";
-        const aspectRatio = this.getAspectRatio(settings);
-        const landscape = this.isLandscape(settings);
-        if (mode === "environment" && !landscape) {
-          await this.stopMediaStream(stream);
-          continue;
-        }
-        const chosen = {
-          stream,
-          label,
-          settings,
-          aspectRatio,
-          landscape,
-          score: this.scoreTrack({
-            settings,
-            label
-          }),
-          requested: size
-        };
-        debug.chosen = {
-          label,
-          settings,
-          aspectRatio,
-          requested: size,
-          source: "fallback-facingMode"
-        };
-        return {
-          chosen,
-          debug
-        };
-      } catch (_) {}
-    }
-    throw new Error("Could not start a suitable camera.");
   }
   async startVideo() {
     try {
@@ -11762,29 +11384,49 @@ class ExtractorVideo {
       if (!videoElem) {
         throw new Error("Video element not found.");
       }
+      if (!navigator.mediaDevices || !navigator.mediaDevices.getUserMedia) {
+        throw new Error("getUserMedia is not available");
+      }
+      if (!window.isSecureContext) {
+        throw new Error("Camera requires HTTPS / secure context");
+      }
       this.video = videoElem;
       this.isRunning = true;
       this.scanStartTime = Date.now();
       const cfgValues = (0,_config__WEBPACK_IMPORTED_MODULE_1__.getScanDocAIConfigValues)();
       const mode = cfgValues.VIDEO_FACING_MODE ?? "environment";
-      const {
-        chosen,
-        debug
-      } = await this.pickBestPhoneCamera(mode);
-      this.video.srcObject = chosen.stream;
-      await this.video.play().catch(e => {
-        console.warn(`Error on video play: ${e}`);
+      await this.stopCurrentStream();
+      const cameraResult = await openBestDocumentCamera({
+        videoElement: this.video,
+        preferredFacingMode: mode
       });
-      this.focusDebug = await this.tryEnableDocumentFocus(chosen.stream);
-      this.cameraDebug = debug;
-      this.video.addEventListener("loadeddata", () => {
-        this.adjustOverlayPosition();
-      });
-      window.addEventListener("resize", () => this.adjustOverlayPosition());
+      this.currentStream = cameraResult.stream;
+      this.lastCameraInfo = cameraResult;
+      try {
+        const focusResult = await tryEnableDocumentFocus(this.currentStream);
+        console.log("Focus result:", focusResult);
+      } catch (focusError) {
+        console.warn("Could not apply focus settings:", focusError);
+      }
+      if (!this._boundLoadedDataHandler) {
+        this._boundLoadedDataHandler = () => this.adjustOverlayPosition();
+        this.video.addEventListener("loadeddata", this._boundLoadedDataHandler);
+      }
+      if (!this._boundResizeHandler) {
+        this._boundResizeHandler = () => this.adjustOverlayPosition();
+        window.addEventListener("resize", this._boundResizeHandler);
+      }
       setTimeout(() => this.adjustOverlayPosition(), 500);
       this.scanStartTime = Date.now();
       setTimeout(() => this.analyzeVideoStream(), ExtractorVideo.FREQUENCY_MS);
       this.showMessage("Starting scanning");
+      console.log("Chosen camera:", {
+        label: cameraResult.label,
+        deviceId: cameraResult.deviceId,
+        strategy: cameraResult.strategy,
+        settings: cameraResult.settings,
+        score: cameraResult.score
+      });
       return true;
     } catch (error) {
       console.error("startVideo failed:", error);
@@ -11798,26 +11440,47 @@ class ExtractorVideo {
       return false;
     }
   }
+  async stopCurrentStream() {
+    await stopStream(this.currentStream);
+    this.currentStream = null;
+    if (this.video) {
+      this.video.srcObject = null;
+    }
+    await delay(200);
+  }
   stopVideo() {
     this.isRunning = false;
     if (this.video) {
-      this.video.pause();
-      if (this.video.srcObject !== undefined && this.video.srcObject !== null) {
-        this.video.srcObject.getTracks().forEach(t => t.stop());
+      try {
+        this.video.pause();
+      } catch (_) {}
+      if (this.video.srcObject) {
+        try {
+          this.video.srcObject.getTracks().forEach(t => t.stop());
+        } catch (_) {}
       }
       this.video.srcObject = null;
     }
+    if (this.currentStream) {
+      try {
+        this.currentStream.getTracks().forEach(t => t.stop());
+      } catch (_) {}
+    }
+    this.currentStream = null;
     clearTimeout(this.turnMessageTimer);
     this.turnMessageTimer = null;
   }
   adjustOverlayPosition() {
     const video = this.video;
     const dot = document.querySelector(".centerGuideDot");
-    if (!video || !dot || video.videoWidth === 0 || video.videoHeight === 0) return;
+    if (!video || !dot || video.videoWidth === 0 || video.videoHeight === 0) {
+      return;
+    }
     const videoRatio = video.videoWidth / video.videoHeight;
     const container = video.parentElement;
     const containerRatio = container.clientWidth / container.clientHeight;
-    let scaleWidth, scaleHeight;
+    let scaleWidth;
+    let scaleHeight;
     if (videoRatio > containerRatio) {
       scaleWidth = container.clientWidth;
       scaleHeight = container.clientWidth / videoRatio;
@@ -11901,87 +11564,86 @@ class ExtractorVideo {
 					}
 				</style>
 			`;
-    } else {
-      return `
-				<div class="desktopFeedback" id="ScanDocAIMessage"></div>
-				<div class="desktopVideoArea">
-					<div class="desktopVideoHolder">
-						<video id="ScanDocAIVideoElement" class="desktopVideo" autoplay muted playsinline></video>
-						<div class="backgroundOverlay"></div>
-						<div class="centerGuideDot"></div>
-					</div>
-				</div>
-		
-				<style>
-					.desktopVideoArea {
-						display: flex;
-						flex-direction: column;
-						gap: 8px;
-						padding: 16px;
-						background-color: rgba(255, 255, 255, 0.05);
-						border: 1px solid ${borderColor};
-						border-radius: 15px;
-						margin-left: 20%;
-						margin-right: 20%;
-					}
-		
-					.desktopVideoHolder {
-						position: relative;
-						width: 100%;
-						overflow: hidden;
-					}
-
-					.desktopVideo {
-						width: 100%;
-						height: auto;
-						margin-left: auto;
-						margin-right: auto;
-						max-width: 100vw;
-						max-height: 100vh;
-					}
-					
-					.centerGuideDot {
-						position: absolute;
-						width: 16px;
-						height: 16px;
-						background-color: #00ff55;
-						border-radius: 50%;
-						box-shadow: 0 0 8px 2px rgba(0, 255, 100, 0.8);
-						z-index: 4;
-						animation: flicker 1s infinite;
-						pointer-events: none;
-						display: none;
-					}
-
-					@keyframes flicker {
-						0%, 100% { opacity: 1; }
-						50% { opacity: 0.3; }
-					}
-
-					.backgroundOverlay {
-						position: absolute;
-						top: 0;
-						left: 0;
-						width: 100%;
-						height: 100%;
-						background-color: rgba(0, 0, 0, 0.051);
-						z-index: 2;
-						pointer-events: none;
-					}
-		
-					.desktopFeedback {
-						position: relative;
-						display: flex;
-						font-size: 22px;
-						font-weight: 600;
-						min-height: 36px;
-						justify-content: center;
-						align-items: center;
-						color: ${messageColor};
-					}
-				</style>
-			`;
     }
+    return `
+			<div class="desktopFeedback" id="ScanDocAIMessage"></div>
+			<div class="desktopVideoArea">
+				<div class="desktopVideoHolder">
+					<video id="ScanDocAIVideoElement" class="desktopVideo" autoplay muted playsinline></video>
+					<div class="backgroundOverlay"></div>
+					<div class="centerGuideDot"></div>
+				</div>
+			</div>
+	
+			<style>
+				.desktopVideoArea {
+					display: flex;
+					flex-direction: column;
+					gap: 8px;
+					padding: 16px;
+					background-color: rgba(255, 255, 255, 0.05);
+					border: 1px solid ${borderColor};
+					border-radius: 15px;
+					margin-left: 20%;
+					margin-right: 20%;
+				}
+	
+				.desktopVideoHolder {
+					position: relative;
+					width: 100%;
+					overflow: hidden;
+				}
+
+				.desktopVideo {
+					width: 100%;
+					height: auto;
+					margin-left: auto;
+					margin-right: auto;
+					max-width: 100vw;
+					max-height: 100vh;
+				}
+				
+				.centerGuideDot {
+					position: absolute;
+					width: 16px;
+					height: 16px;
+					background-color: #00ff55;
+					border-radius: 50%;
+					box-shadow: 0 0 8px 2px rgba(0, 255, 100, 0.8);
+					z-index: 4;
+					animation: flicker 1s infinite;
+					pointer-events: none;
+					display: none;
+				}
+
+				@keyframes flicker {
+					0%, 100% { opacity: 1; }
+					50% { opacity: 0.3; }
+				}
+
+				.backgroundOverlay {
+					position: absolute;
+					top: 0;
+					left: 0;
+					width: 100%;
+					height: 100%;
+					background-color: rgba(0, 0, 0, 0.051);
+					z-index: 2;
+					pointer-events: none;
+				}
+	
+				.desktopFeedback {
+					position: relative;
+					display: flex;
+					font-size: 22px;
+					font-weight: 600;
+					min-height: 36px;
+					justify-content: center;
+					align-items: center;
+					color: ${messageColor};
+				}
+			</style>
+		`;
   }
 }
 let EXTRACTION_VIDEO = undefined;
@@ -12011,6 +11673,336 @@ function getExtractionVideo(tokenOrCallback, maybeCallback) {
   }
   return EXTRACTION_VIDEO;
 }
+function delay(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+async function stopStream(stream) {
+  if (!stream) return;
+  for (const track of stream.getTracks()) {
+    try {
+      track.stop();
+    } catch (_) {}
+  }
+}
+function getAspectRatio(settings = {}) {
+  if (typeof settings.aspectRatio === "number" && settings.aspectRatio > 0) {
+    return settings.aspectRatio;
+  }
+  if (settings.width && settings.height) {
+    return settings.width / settings.height;
+  }
+  return null;
+}
+async function attachStreamToVideo(videoEl, stream) {
+  videoEl.srcObject = stream;
+  try {
+    await videoEl.play();
+  } catch (_) {}
+}
+function getSupportedConstraintsSafe() {
+  try {
+    return navigator.mediaDevices?.getSupportedConstraints?.() || {};
+  } catch (_) {
+    return {};
+  }
+}
+function buildDocumentScanConstraints(mode = "environment") {
+  const supported = getSupportedConstraintsSafe();
+  const video = {};
+  if (supported.facingMode) {
+    video.facingMode = typeof mode === "string" ? {
+      ideal: mode
+    } : mode || {
+      ideal: "environment"
+    };
+  }
+  if (supported.width) {
+    video.width = {
+      ideal: 1920
+    };
+  }
+  if (supported.height) {
+    video.height = {
+      ideal: 1080
+    };
+  }
+  if (supported.aspectRatio) {
+    video.aspectRatio = {
+      ideal: 16 / 9
+    };
+  }
+  return {
+    video,
+    audio: false
+  };
+}
+function buildDeviceConstraints(deviceId) {
+  const supported = getSupportedConstraintsSafe();
+  const video = {
+    deviceId: {
+      exact: deviceId
+    }
+  };
+  if (supported.width) {
+    video.width = {
+      ideal: 1920
+    };
+  }
+  if (supported.height) {
+    video.height = {
+      ideal: 1080
+    };
+  }
+  if (supported.aspectRatio) {
+    video.aspectRatio = {
+      ideal: 16 / 9
+    };
+  }
+  return {
+    video,
+    audio: false
+  };
+}
+async function enumerateVideoInputDevices() {
+  if (!navigator.mediaDevices?.enumerateDevices) return [];
+  try {
+    const devices = await navigator.mediaDevices.enumerateDevices();
+    return devices.filter(d => d.kind === "videoinput");
+  } catch (error) {
+    console.warn("enumerateDevices failed:", error);
+    return [];
+  }
+}
+function normalizeLabel(label = "") {
+  return String(label).trim().toLowerCase();
+}
+function isLikelyRearCamera(label = "") {
+  const v = normalizeLabel(label);
+  return v.includes("back") || v.includes("rear") || v.includes("environment") || v.includes("world");
+}
+function isLikelyUltraWideOrMacro(label = "") {
+  const v = normalizeLabel(label);
+  return v.includes("ultra") || v.includes("ultrawide") || v.includes("wide angle") || v.includes("0.5") || v.includes("macro") || v.includes("fisheye");
+}
+function scoreCameraCandidate({
+  label,
+  settings
+}) {
+  const width = Number(settings?.width || 0);
+  const height = Number(settings?.height || 0);
+  const pixels = width * height;
+  const aspectRatio = getAspectRatio(settings) || 0;
+  let score = 0;
+  score += pixels;
+  if (isLikelyRearCamera(label)) {
+    score += 5_000_000;
+  }
+  if (isLikelyUltraWideOrMacro(label)) {
+    score -= 8_000_000;
+  }
+  if (aspectRatio > 1.65 && aspectRatio < 1.85) {
+    score += 750_000;
+  }
+  if (aspectRatio > 2.1) {
+    score -= 2_000_000;
+  }
+  if (width >= 1920) {
+    score += 500_000;
+  }
+  if (width < 1280 || height < 720) {
+    score -= 3_000_000;
+  }
+  return score;
+}
+async function probeCameraCandidate(device, videoElement) {
+  let stream = null;
+  try {
+    stream = await navigator.mediaDevices.getUserMedia(buildDeviceConstraints(device.deviceId));
+    await attachStreamToVideo(videoElement, stream);
+    await waitForVideoReady(videoElement, 800);
+    const track = stream.getVideoTracks?.()[0];
+    const settings = track?.getSettings?.() || {};
+    return {
+      ok: true,
+      device,
+      stream,
+      label: track?.label || device.label || "",
+      deviceId: settings.deviceId || device.deviceId,
+      settings,
+      aspectRatio: getAspectRatio(settings),
+      score: scoreCameraCandidate({
+        label: track?.label || device.label || "",
+        settings
+      })
+    };
+  } catch (error) {
+    if (stream) {
+      await stopStream(stream);
+    }
+    return {
+      ok: false,
+      device,
+      error,
+      score: Number.NEGATIVE_INFINITY
+    };
+  }
+}
+function waitForVideoReady(videoEl, timeoutMs = 800) {
+  return new Promise(resolve => {
+    if (videoEl.readyState >= 2 && videoEl.videoWidth > 0 && videoEl.videoHeight > 0) {
+      resolve();
+      return;
+    }
+    let done = false;
+    const finish = () => {
+      if (done) return;
+      done = true;
+      videoEl.removeEventListener("loadeddata", onReady);
+      videoEl.removeEventListener("canplay", onReady);
+      clearTimeout(timer);
+      resolve();
+    };
+    const onReady = () => finish();
+    const timer = setTimeout(finish, timeoutMs);
+    videoEl.addEventListener("loadeddata", onReady, {
+      once: true
+    });
+    videoEl.addEventListener("canplay", onReady, {
+      once: true
+    });
+  });
+}
+async function tryEnableDocumentFocus(stream) {
+  const track = stream?.getVideoTracks?.()[0];
+  if (!track) {
+    return {
+      ok: false,
+      reason: "No video track found"
+    };
+  }
+  if (!track.getCapabilities || !track.applyConstraints) {
+    return {
+      ok: false,
+      reason: "Focus APIs unavailable on this browser/device",
+      settingsBefore: track.getSettings ? track.getSettings() : null
+    };
+  }
+  const caps = track.getCapabilities();
+  const result = {
+    ok: true,
+    capabilities: caps,
+    attempts: [],
+    settingsBefore: track.getSettings ? track.getSettings() : null
+  };
+  try {
+    let applied = false;
+    if (Array.isArray(caps.focusMode) && caps.focusMode.includes("continuous")) {
+      await track.applyConstraints({
+        advanced: [{
+          focusMode: "continuous"
+        }]
+      });
+      result.attempts.push("Applied focusMode=continuous");
+      applied = true;
+    }
+    if (caps.focusDistance) {
+      const min = caps.focusDistance.min ?? 0;
+      const max = caps.focusDistance.max ?? 0;
+      const docDistance = min + (max - min) * 0.3;
+      const advanced = [];
+      if (Array.isArray(caps.focusMode) && caps.focusMode.includes("manual")) {
+        advanced.push({
+          focusMode: "manual"
+        });
+      }
+      advanced.push({
+        focusDistance: docDistance
+      });
+      await track.applyConstraints({
+        advanced
+      });
+      result.attempts.push(`Applied focusDistance=${docDistance}`);
+      applied = true;
+    }
+    if (!applied) {
+      result.ok = false;
+      result.reason = "No supported focus controls were exposed";
+    }
+    result.settingsAfter = track.getSettings ? track.getSettings() : null;
+    return result;
+  } catch (err) {
+    result.ok = false;
+    result.error = err.message || String(err);
+    result.settingsAfter = track.getSettings ? track.getSettings() : null;
+    return result;
+  }
+}
+async function openBestDocumentCamera({
+  videoElement,
+  preferredFacingMode = "environment"
+}) {
+  if (!navigator.mediaDevices || !navigator.mediaDevices.getUserMedia) {
+    throw new Error("getUserMedia is not available");
+  }
+  if (!window.isSecureContext) {
+    throw new Error("Camera requires HTTPS / secure context");
+  }
+  let bootstrapStream = null;
+  try {
+    bootstrapStream = await navigator.mediaDevices.getUserMedia(buildDocumentScanConstraints(preferredFacingMode));
+    await attachStreamToVideo(videoElement, bootstrapStream);
+    await waitForVideoReady(videoElement, 800);
+  } catch (preferredError) {
+    console.warn("Preferred camera open failed, falling back:", preferredError);
+    bootstrapStream = await navigator.mediaDevices.getUserMedia({
+      video: true,
+      audio: false
+    });
+    await attachStreamToVideo(videoElement, bootstrapStream);
+    await waitForVideoReady(videoElement, 800);
+  }
+  const bootstrapTrack = bootstrapStream.getVideoTracks?.()[0];
+  const bootstrapSettings = bootstrapTrack?.getSettings?.() || {};
+  const bootstrapLabel = bootstrapTrack?.label || "";
+  const bootstrapDeviceId = bootstrapSettings.deviceId || null;
+  let best = {
+    ok: true,
+    device: null,
+    stream: bootstrapStream,
+    label: bootstrapLabel,
+    deviceId: bootstrapDeviceId,
+    settings: bootstrapSettings,
+    aspectRatio: getAspectRatio(bootstrapSettings),
+    score: scoreCameraCandidate({
+      label: bootstrapLabel,
+      settings: bootstrapSettings
+    }),
+    strategy: "bootstrap"
+  };
+  const devices = await enumerateVideoInputDevices();
+  if (devices.length <= 1) {
+    return best;
+  }
+  const rearDevices = devices.filter(d => isLikelyRearCamera(d.label));
+  const candidates = rearDevices.length > 0 ? rearDevices : devices;
+  for (const device of candidates) {
+    if (!device.deviceId) continue;
+    if (device.deviceId === bootstrapDeviceId) continue;
+    const probed = await probeCameraCandidate(device, videoElement);
+    if (!probed.ok) continue;
+    if (probed.score > best.score) {
+      await stopStream(best.stream);
+      best = {
+        ...probed,
+        strategy: "probed-better-camera"
+      };
+    } else {
+      await stopStream(probed.stream);
+    }
+  }
+  await attachStreamToVideo(videoElement, best.stream);
+  return best;
+}
 
 /***/ }),
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "scandoc-ai-components",
   "author": "ScanDoc-AI",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "private": false,
   "description": "Pure JavaScript package for integrating ScanDoc-AI services.",
   "keywords": [