@mleonard9/vin-scanner 1.3.0 → 1.4.2

package/src/index.tsx

@@ -1,10 +1,12 @@
-import React, { forwardRef, useMemo } from 'react';
+import React, { forwardRef, useMemo, useCallback } from 'react';
 import {
   Camera as VisionCamera,
   type ReadonlyFrameProcessor,
   useFrameProcessor,
 } from 'react-native-vision-camera';
 import { useRunOnJS } from 'react-native-worklets-core';
+import { Gesture, GestureDetector } from 'react-native-gesture-handler';
+import { runOnJS } from 'react-native-reanimated';
 import { createBarcodeScannerPlugin } from './scanBarcodes';
 import { createTextRecognitionPlugin } from './scanText';
 import type {
@@ -35,11 +37,44 @@ export const Camera = forwardRef(function Camera(
   const barcodeScanner = useBarcodeScanner(resolvedOptions.barcode);
   const textScanner = useTextScanner(resolvedOptions.text);
 
+  const lastEmittedVin = React.useRef<string | null>(null);
+  const lastEmitTimestamp = React.useRef(0);
+  const lastFrameTimestampRef = React.useRef(0);
+  const frameCounterRef = React.useRef(0);
+  const sessionSeen = React.useRef<Set<string>>(new Set());
+
   const handleDetections = useRunOnJS(
     (payload: WorkletPayload) => {
       const candidates = buildVinCandidates(payload, resolvedOptions);
-      const firstCandidate = pickFirstCandidate(candidates, resolvedOptions);
+      const barcodeCandidates = candidates.filter(
+        (c) => c.source === 'barcode'
+      );
+      const textCandidates = candidates.filter((c) => c.source === 'text');
+
+      if (barcodeCandidates.length > 0) {
+        const first = pickFirstCandidate(barcodeCandidates, resolvedOptions);
+        callback({
+          timestamp: payload.timestamp,
+          duration: 0,
+          candidates: barcodeCandidates,
+          firstCandidate: first,
+          raw: {
+            barcodes: payload.barcodes ?? [],
+            textBlocks: payload.textBlocks ?? [],
+          },
+        });
+        return;
+      }
+
+      if (
+        resolvedOptions.text.requireConfirmation &&
+        textCandidates.length > 0
+      ) {
+        options?.onTextPending?.(textCandidates);
+        return;
+      }
 
+      const firstCandidate = pickFirstCandidate(candidates, resolvedOptions);
       callback({
         timestamp: payload.timestamp,
         duration: 0,
@@ -51,41 +86,201 @@ export const Camera = forwardRef(function Camera(
         },
       });
     },
-    [callback, resolvedOptions]
+    [callback, options?.onTextPending, resolvedOptions]
   );
 
   const scanBarcodes = barcodeScanner?.scanBarcodes;
   const scanText = textScanner?.scanText;
 
+  const noBarcodeFrameCount = React.useRef(0);
+  const useBarcodeFallback = React.useRef(false);
+
   const frameProcessor: ReadonlyFrameProcessor = useFrameProcessor(
     (frame) => {
       'worklet';
-      const barcodes = scanBarcodes ? scanBarcodes(frame) : [];
-      const textBlocks = scanText ? scanText(frame) : [];
-      handleDetections({
+
+      const now =
+        typeof frame?.timestamp === 'number' ? frame.timestamp : Date.now();
+
+      // Max FPS throttle (matches hook behavior)
+      const maxFps = resolvedOptions.detection.maxFrameRate;
+      if (maxFps > 0) {
+        const minInterval = 1000 / maxFps;
+        if (
+          lastFrameTimestampRef.current > 0 &&
+          now - lastFrameTimestampRef.current < minInterval
+        ) {
+          return;
+        }
+        lastFrameTimestampRef.current = now;
+      }
+
+      const orientationOverride =
+        resolvedOptions.detection.forceOrientation ?? null;
+      const regionOverride = resolvedOptions.detection.scanRegion ?? null;
+
+      // Frame quality gate (luma + sharpness)
+      const minLuma = resolvedOptions.detection.minLuma;
+      const minSharpness = resolvedOptions.detection.minSharpness;
+      if (minLuma > 0 || minSharpness > 0) {
+        const planes = (frame as any)?.planes;
+        if (planes?.length > 0) {
+          const yPlane = planes[0];
+          const bytes: Uint8Array | undefined = yPlane?.bytes;
+          const width: number | undefined = yPlane?.width;
+          const height: number | undefined = yPlane?.height;
+          const stride: number | undefined = yPlane?.bytesPerRow;
+          if (bytes && width && height && stride) {
+            let lumaSum = 0;
+            const sampleStep = 8;
+            const sampleCount = Math.floor(bytes.length / sampleStep);
+            for (let i = 0; i < bytes.length; i += sampleStep) {
+              lumaSum += bytes[i]!;
+            }
+            const meanLuma = lumaSum / Math.max(1, sampleCount);
+            if (minLuma > 0 && meanLuma < minLuma) {
+              return;
+            }
+
+            if (minSharpness > 0) {
+              const step = Math.max(2, Math.floor(width / 96));
+              let sharpAccum = 0;
+              let sharpCount = 0;
+              for (let y = step; y < height - step; y += step) {
+                const row = y * stride;
+                for (let x = step; x < width - step; x += step) {
+                  const idx = row + x;
+                  const gx = bytes[idx + 1]! - bytes[idx - 1]!;
+                  const gy = bytes[idx + stride]! - bytes[idx - stride]!;
+                  sharpAccum += Math.abs(gx) + Math.abs(gy);
+                  sharpCount += 1;
+                }
+              }
+              const sharpness = sharpAccum / Math.max(1, sharpCount);
+              if (sharpness < minSharpness) {
+                return;
+              }
+            }
+          }
+        }
+      }
+
+      const pluginArgs =
+        orientationOverride || regionOverride
+          ? {
+              ...(orientationOverride && { orientation: orientationOverride }),
+              ...(regionOverride && { scanRegion: regionOverride }),
+            }
+          : undefined;
+
+      // Run barcode every frame
+      const barcodes = scanBarcodes
+        ? scanBarcodes(
+            frame,
+            useBarcodeFallback.current ? { all: true } : pluginArgs
+          )
+        : [];
+
+      // Run text every Nth frame per textScanInterval
+      frameCounterRef.current += 1;
+      const frameIndex = frameCounterRef.current;
+      const textScanInterval = resolvedOptions.detection.textScanInterval;
+      const shouldRunText =
+        scanText &&
+        (textScanInterval <= 1 || frameIndex % textScanInterval === 0);
+      let textBlocks =
+        shouldRunText && scanText ? (scanText(frame, pluginArgs) ?? []) : [];
+      if (
+        scanText &&
+        (textBlocks ?? []).length === 0 &&
+        (barcodes ?? []).length === 0 &&
+        !shouldRunText
+      ) {
+        textBlocks = scanText(frame, pluginArgs) ?? [];
+      }
+
+      const payload = {
         barcodes: barcodes ?? [],
         textBlocks: textBlocks ?? [],
-        timestamp:
-          typeof frame?.timestamp === 'number' ? frame.timestamp : Date.now(),
-      });
+        timestamp: now,
+      } as WorkletPayload;
+
+      const candidates = buildVinCandidates(payload, resolvedOptions).filter(
+        (c) => c.confidence >= resolvedOptions.detection.minConfidence
+      );
+      const firstCandidate = pickFirstCandidate(candidates, resolvedOptions);
+
+      // Adaptive barcode fallback: if no barcode hits for N frames, scan all formats.
+      const hasBarcode = (payload.barcodes ?? []).length > 0;
+      if (!hasBarcode) {
+        noBarcodeFrameCount.current += 1;
+        if (
+          noBarcodeFrameCount.current >=
+          resolvedOptions.detection.barcodeFallbackAfter
+        ) {
+          useBarcodeFallback.current = true;
+        }
+      } else {
+        noBarcodeFrameCount.current = 0;
+        useBarcodeFallback.current = false;
+      }
+
+      // Duplicate debounce (matches hook behavior)
+      if (firstCandidate) {
+        const debounceMs = resolvedOptions.duplicateDebounceMs ?? 1500;
+        const isDuplicate =
+          firstCandidate.value === lastEmittedVin.current &&
+          now - lastEmitTimestamp.current < debounceMs;
+        const seen = sessionSeen.current.has(firstCandidate.value);
+
+        if (isDuplicate || seen) {
+          return;
+        }
+        lastEmittedVin.current = firstCandidate.value;
+        lastEmitTimestamp.current = now;
+        sessionSeen.current.add(firstCandidate.value);
+      }
+
+      handleDetections(payload);
+    },
+    [scanBarcodes, scanText, handleDetections, resolvedOptions]
+  );
+
+  // Tap to focus callback
+  const focus = useCallback(
+    (point: { x: number; y: number }) => {
+      const camera = (ref as any)?.current;
+      if (camera == null) return;
+      camera.focus(point);
     },
-    [scanBarcodes, scanText, handleDetections]
+    [ref]
+  );
+
+  // Create tap gesture for focus
+  const tapGesture = Gesture.Tap().onEnd(
+    ({ x, y }: { x: number; y: number }) => {
+      runOnJS(focus)({ x, y });
+    }
   );
 
   return (
     <>
       {!!device && (
-        <VisionCamera
-          pixelFormat="yuv"
-          ref={ref}
-          frameProcessor={frameProcessor}
-          device={device}
-          enableZoomGesture={true}
-          lowLightBoost={options?.cameraSettings?.lowLightBoost ?? true}
-          videoStabilizationMode={options?.cameraSettings?.videoStabilizationMode ?? 'off'}
-          fps={options?.cameraSettings?.fps ?? 30}
-          {...rest}
-        />
+        <GestureDetector gesture={tapGesture}>
+          <VisionCamera
+            pixelFormat="yuv"
+            ref={ref}
+            frameProcessor={frameProcessor}
+            device={device}
+            enableZoomGesture={true}
+            lowLightBoost={options?.cameraSettings?.lowLightBoost ?? true}
+            videoStabilizationMode={
+              options?.cameraSettings?.videoStabilizationMode ?? 'cinematic'
+            }
+            fps={Math.min(30, Math.max(24, options?.cameraSettings?.fps ?? 24))}
+            {...rest}
+          />
+        </GestureDetector>
       )}
     </>
   );
@@ -135,5 +330,7 @@ export type {
 } from './types';
 
 export { useVinScanner } from './useVinScanner';
-export { VinScannerOverlay } from './VinScannerOverlay';
 export { isValidVin } from './vinUtils';
+export { TextVinPrompt } from './TextVinPrompt';
+export { PendingVinBanner } from './PendingVinBanner';
+export { ManualVinInput } from './ManualVinInput';

package/src/scanBarcodes.ts

@@ -116,7 +116,11 @@ const mergeArgs = (
   'worklet';
   const merged: BarcodePluginArgs = { ...baseArgs };
   if (overrides) {
-    const { orientation: overrideOrientation, scanRegion: overrideScanRegion, ...formatMap } = overrides;
+    const {
+      orientation: overrideOrientation,
+      scanRegion: overrideScanRegion,
+      ...formatMap
+    } = overrides;
     Object.entries(formatMap).forEach(([key, value]) => {
       merged[key as BarcodeFormat] = value as boolean | undefined;
     });

package/src/scanText.ts

@@ -90,7 +90,11 @@ const mergeTextArgs = (
     ...base,
   };
   if (overrides) {
-    const { orientation: overrideOrientation, scanRegion: overrideScanRegion, ...rest } = overrides;
+    const {
+      orientation: overrideOrientation,
+      scanRegion: overrideScanRegion,
+      ...rest
+    } = overrides;
     Object.assign(merged, rest);
     if (overrideScanRegion) {
       merged.scanRegion = overrideScanRegion;

package/src/types.ts

@@ -102,7 +102,12 @@ export type BoundingBox = {
 
 export type VinCandidateSource = 'barcode' | 'text';
 
-export type VinTextOrigin = 'rawValue' | 'displayValue' | 'block' | 'line' | 'element';
+export type VinTextOrigin =
+  | 'rawValue'
+  | 'displayValue'
+  | 'block'
+  | 'line'
+  | 'element';
 
 export type VinCandidate = {
   value: string;
@@ -112,9 +117,9 @@ export type VinCandidate = {
   origin?: VinTextOrigin;
   boundingBox?: BoundingBox;
   rawPayload?:
-  | BarcodeDetection
-  | TextDetection
-  | { resultText?: string;[key: string]: unknown };
+    | BarcodeDetection
+    | TextDetection
+    | { resultText?: string; [key: string]: unknown };
 };
 
 export type VinScannerEvent = {
@@ -147,6 +152,17 @@ export type BarcodeScannerOptions = {
 export type TextScannerOptions = {
   enabled?: boolean;
   language?: TextRecognitionLanguage;
+  /**
+   * When true, text VINs are surfaced via `onTextPending` and must be
+   * confirmed manually; barcode VINs still emit immediately.
+   * Default: false
+   */
+  requireConfirmation?: boolean;
+  /**
+   * Auto-dismiss pending text candidates after this many ms.
+   * Default: 5000
+   */
+  pendingTtlMs?: number;
 };
 
 export type ScanRegion = {
@@ -196,9 +212,29 @@ export type DetectionOptions = {
   /**
    * Enable intelligent frame quality checks to skip blurry or dark frames.
    * This improves accuracy by only processing high-quality frames.
-   * Default: true
+   * Note: currently unused; retained for backward compatibility.
    */
   enableFrameQualityCheck?: boolean;
+  /**
+   * Minimum average luma (0-255) required to process the frame. Lower = darker.
+   * Set to 0 to disable.
+   */
+  minLuma?: number;
+  /**
+   * Minimum sharpness score (simple gradient metric) required to process.
+   * Set to 0 to disable.
+   */
+  minSharpness?: number;
+  /**
+   * Minimum candidate confidence required before emitting.
+   * Default: 0.6
+   */
+  minConfidence?: number;
+  /**
+   * Frames without barcode hits before falling back to scanning all formats.
+   * Default: 45 frames.
+   */
+  barcodeFallbackAfter?: number;
 };
 
 export type OverlayColors = {
@@ -211,11 +247,11 @@ export type OverlayColors = {
 };
 
 export type CameraSettings = {
-  /** Target FPS for camera. Default: 30 */
+  /** Target FPS for camera. Clamped to 24–30. Default: 24 */
   fps?: number;
   /** Enable low light boost. Default: true */
   lowLightBoost?: boolean;
-  /** Video stabilization mode. Default: 'off' */
+  /** Video stabilization mode. Default: 'cinematic' */
   videoStabilizationMode?: 'off' | 'standard' | 'cinematic' | 'auto';
 };
 
@@ -225,13 +261,21 @@ export type VinScannerOptions = {
   detection?: DetectionOptions;
   onResult?: (result: VinCandidate[], event: VinScannerEvent) => void;
   /**
-   * Show AR overlay with bounding boxes around detected VINs.
-   * Requires @shopify/react-native-skia peer dependency.
-   * Default: false
+   * Called when text candidates are detected and `text.requireConfirmation` is true.
+   * Use this to show a confirmation UI and then call `confirmTextCandidate`.
+   */
+  onTextPending?: (pending: VinCandidate[]) => void;
+  /**
+   * Enable built-in haptic notifications (if react-native-haptic-feedback is installed).
+   * Default: true
+   */
+  haptics?: boolean;
+  /**
+   * Deprecated: overlay component removed. Ignored.
    */
   showOverlay?: boolean;
   /**
-   * Custom colors for overlay bounding boxes based on confidence.
+   * Deprecated: overlay component removed. Ignored.
    */
   overlayColors?: Partial<OverlayColors>;
   /**