react-native-rectangle-doc-scanner 0.66.0 → 0.69.0

package/dist/DocScanner.d.ts

@@ -1,10 +1,15 @@
 import React, { ReactNode } from 'react';
 import type { Point } from './types';
-/**
- * Detection configuration is no longer used now that the native
- * implementation handles edge detection. Keeping it for backwards
- * compatibility with existing consumer code.
- */
+type PictureEvent = {
+    croppedImage?: string | null;
+    initialImage?: string;
+    width?: number;
+    height?: number;
+};
+type DocScannerHandle = {
+    capture: () => Promise<PictureEvent>;
+    reset: () => void;
+};
 export interface DetectionConfig {
     processingWidth?: number;
     cannyLowThreshold?: number;
@@ -32,5 +37,5 @@ interface Props {
     gridLineWidth?: number;
     detectionConfig?: DetectionConfig;
 }
-export declare const DocScanner: React.FC<Props>;
-export {};
+export declare const DocScanner: React.ForwardRefExoticComponent<Props & React.RefAttributes<DocScannerHandle>>;
+export type { DocScannerHandle };

package/dist/DocScanner.js

@@ -32,83 +32,138 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DocScanner = void 0;
 const react_1 = __importStar(require("react"));
 const react_native_1 = require("react-native");
-const react_native_document_scanner_plugin_1 = __importDefault(require("react-native-document-scanner-plugin"));
 const overlay_1 = require("./utils/overlay");
-const NativeDocumentScanner = react_native_document_scanner_plugin_1.default;
+const MODULE_NAME = 'RNRDocScannerModule';
+const VIEW_NAME = 'RNRDocScannerView';
+const NativeDocScannerModule = react_native_1.NativeModules[MODULE_NAME];
+if (!NativeDocScannerModule) {
+    const fallbackMessage = `The native module '${MODULE_NAME}' is not linked. Make sure you have run pod install, ` +
+        `synced Gradle, and rebuilt the app after installing 'react-native-rectangle-doc-scanner'.`;
+    throw new Error(fallbackMessage);
+}
+const NativeDocScanner = (0, react_native_1.requireNativeComponent)(VIEW_NAME);
 const DEFAULT_OVERLAY_COLOR = '#e7a649';
 const GRID_COLOR_FALLBACK = 'rgba(231, 166, 73, 0.35)';
-const DocScanner = ({ onCapture, overlayColor = DEFAULT_OVERLAY_COLOR, autoCapture = true, minStableFrames = 8, enableTorch = false, quality, useBase64 = false, children, showGrid = true, gridColor, gridLineWidth = 2, }) => {
-    const scannerRef = (0, react_1.useRef)(null);
+exports.DocScanner = (0, react_1.forwardRef)(({ onCapture, overlayColor = DEFAULT_OVERLAY_COLOR, autoCapture = true, minStableFrames = 8, enableTorch = false, quality = 90, useBase64 = false, children, showGrid = true, gridColor, gridLineWidth = 2, }, ref) => {
+    const viewRef = (0, react_1.useRef)(null);
     const capturingRef = (0, react_1.useRef)(false);
     const [quad, setQuad] = (0, react_1.useState)(null);
+    const [stable, setStable] = (0, react_1.useState)(0);
     const [frameSize, setFrameSize] = (0, react_1.useState)(null);
     const effectiveGridColor = (0, react_1.useMemo)(() => gridColor ?? GRID_COLOR_FALLBACK, [gridColor]);
-    const handleLayout = (0, react_1.useCallback)((event) => {
-        const { width, height } = event.nativeEvent.layout;
-        if (width > 0 && height > 0) {
-            setFrameSize({ width, height });
+    const ensureViewHandle = (0, react_1.useCallback)(() => {
+        const nodeHandle = (0, react_native_1.findNodeHandle)(viewRef.current);
+        if (!nodeHandle) {
+            throw new Error('Unable to obtain native view handle for DocScanner.');
         }
+        return nodeHandle;
     }, []);
-    const handleRectangleDetect = (0, react_1.useCallback)((event) => {
-        const coordinates = event?.rectangleCoordinates;
-        if (!coordinates) {
-            setQuad(null);
-            return;
+    const resetNativeStability = (0, react_1.useCallback)(() => {
+        try {
+            const handle = ensureViewHandle();
+            NativeDocScannerModule.reset(handle);
         }
-        const nextQuad = [
-            coordinates.topLeft,
-            coordinates.topRight,
-            coordinates.bottomRight,
-            coordinates.bottomLeft,
-        ];
-        setQuad(nextQuad);
-    }, []);
-    const handlePictureTaken = (0, react_1.useCallback)((event) => {
+        catch (error) {
+            console.warn('[DocScanner] unable to reset native stability', error);
+        }
+    }, [ensureViewHandle]);
+    const emitCaptureResult = (0, react_1.useCallback)((payload) => {
         capturingRef.current = false;
-        const path = event?.croppedImage ?? event?.initialImage;
+        const path = payload.croppedImage ?? payload.initialImage;
         if (!path) {
             return;
         }
-        const width = event?.width ?? frameSize?.width ?? 0;
-        const height = event?.height ?? frameSize?.height ?? 0;
+        const width = payload.width ?? frameSize?.width ?? 0;
+        const height = payload.height ?? frameSize?.height ?? 0;
         onCapture?.({
             path,
             quad,
             width,
             height,
         });
-    }, [frameSize, onCapture, quad]);
+        setStable(0);
+        resetNativeStability();
+    }, [frameSize, onCapture, quad, resetNativeStability]);
+    const handleRectangleDetect = (0, react_1.useCallback)((event) => {
+        const { rectangleCoordinates, stableCounter, frameWidth, frameHeight } = event.nativeEvent;
+        setStable(stableCounter);
+        setFrameSize({ width: frameWidth, height: frameHeight });
+        if (!rectangleCoordinates) {
+            setQuad(null);
+            return;
+        }
+        setQuad([
+            rectangleCoordinates.topLeft,
+            rectangleCoordinates.topRight,
+            rectangleCoordinates.bottomRight,
+            rectangleCoordinates.bottomLeft,
+        ]);
+        if (autoCapture && stableCounter >= minStableFrames) {
+            triggerCapture();
+        }
+    }, [autoCapture, minStableFrames]);
+    const handlePictureTaken = (0, react_1.useCallback)((event) => {
+        emitCaptureResult(event.nativeEvent);
+    }, [emitCaptureResult]);
+    const captureNative = (0, react_1.useCallback)(() => {
+        if (capturingRef.current) {
+            return Promise.reject(new Error('capture_in_progress'));
+        }
+        try {
+            const handle = ensureViewHandle();
+            capturingRef.current = true;
+            return NativeDocScannerModule.capture(handle)
+                .then((result) => {
+                emitCaptureResult(result);
+                return result;
+            })
+                .catch((error) => {
+                capturingRef.current = false;
+                throw error;
+            });
+        }
+        catch (error) {
+            capturingRef.current = false;
+            return Promise.reject(error);
+        }
+    }, [emitCaptureResult, ensureViewHandle]);
+    const triggerCapture = (0, react_1.useCallback)(() => {
+        if (capturingRef.current) {
+            return;
+        }
+        captureNative().catch((error) => {
+            console.warn('[DocScanner] capture failed', error);
+        });
+    }, [captureNative]);
     const handleManualCapture = (0, react_1.useCallback)(() => {
-        if (autoCapture || capturingRef.current || !scannerRef.current) {
+        if (autoCapture) {
             return;
         }
-        capturingRef.current = true;
-        scannerRef.current
-            .capture()
-            .catch((error) => {
+        captureNative().catch((error) => {
             console.warn('[DocScanner] manual capture failed', error);
-            capturingRef.current = false;
         });
-    }, [autoCapture]);
-    return (react_1.default.createElement(react_native_1.View, { style: styles.container, onLayout: handleLayout },
-        react_1.default.createElement(NativeDocumentScanner, { ref: (instance) => {
-                scannerRef.current = instance;
-            }, style: react_native_1.StyleSheet.absoluteFill, overlayColor: "transparent", detectionCountBeforeCapture: autoCapture ? minStableFrames : 10000, enableTorch: enableTorch, hideControls: true, useBase64: useBase64, quality: quality, onRectangleDetect: handleRectangleDetect, onPictureTaken: handlePictureTaken }),
+    }, [autoCapture, captureNative]);
+    (0, react_1.useImperativeHandle)(ref, () => ({
+        capture: captureNative,
+        reset: () => {
+            setStable(0);
+            resetNativeStability();
+        },
+    }), [captureNative, resetNativeStability]);
+    return (react_1.default.createElement(react_native_1.View, { style: styles.container },
+        react_1.default.createElement(NativeDocScanner, { ref: viewRef, style: react_native_1.StyleSheet.absoluteFill, detectionCountBeforeCapture: minStableFrames, autoCapture: autoCapture, enableTorch: enableTorch, quality: quality, useBase64: useBase64, onRectangleDetect: handleRectangleDetect, onPictureTaken: handlePictureTaken }),
         react_1.default.createElement(overlay_1.Overlay, { quad: quad, color: overlayColor, frameSize: frameSize, showGrid: showGrid, gridColor: effectiveGridColor, gridLineWidth: gridLineWidth }),
         !autoCapture && (react_1.default.createElement(react_native_1.TouchableOpacity, { style: styles.button, onPress: handleManualCapture })),
         children));
-};
-exports.DocScanner = DocScanner;
+});
 const styles = react_native_1.StyleSheet.create({
     container: {
         flex: 1,
+        backgroundColor: '#000',
     },
     button: {
         position: 'absolute',

package/dist/FullDocScanner.d.ts

@@ -21,6 +21,9 @@ export interface FullDocScannerProps {
     onClose?: () => void;
     detectionConfig?: DetectionConfig;
     overlayColor?: string;
+    gridColor?: string;
+    gridLineWidth?: number;
+    showGrid?: boolean;
     overlayStrokeColor?: string;
     handlerColor?: string;
     strings?: FullDocScannerStrings;

package/dist/FullDocScanner.js

@@ -41,12 +41,13 @@ const CropEditor_1 = require("./CropEditor");
 const coordinate_1 = require("./utils/coordinate");
 const stripFileUri = (value) => value.replace(/^file:\/\//, '');
 const ensureFileUri = (value) => (value.startsWith('file://') ? value : `file://${value}`);
-const FullDocScanner = ({ onResult, onClose, detectionConfig, overlayColor = '#3170f3', overlayStrokeColor = '#3170f3', handlerColor = '#3170f3', strings, manualCapture = false, minStableFrames, onError, }) => {
+const FullDocScanner = ({ onResult, onClose, detectionConfig, overlayColor = '#3170f3', gridColor, gridLineWidth, showGrid, overlayStrokeColor = '#3170f3', handlerColor = '#3170f3', strings, manualCapture = false, minStableFrames, onError, }) => {
     const [screen, setScreen] = (0, react_1.useState)('scanner');
     const [capturedDoc, setCapturedDoc] = (0, react_1.useState)(null);
     const [cropRectangle, setCropRectangle] = (0, react_1.useState)(null);
     const [imageSize, setImageSize] = (0, react_1.useState)(null);
     const [processing, setProcessing] = (0, react_1.useState)(false);
+    const resolvedGridColor = gridColor ?? overlayColor;
     const mergedStrings = (0, react_1.useMemo)(() => ({
         captureHint: strings?.captureHint ?? 'Align the document within the frame.',
         manualHint: strings?.manualHint ?? 'Tap the button below to capture.',
@@ -153,7 +154,7 @@ const FullDocScanner = ({ onResult, onClose, detectionConfig, overlayColor = '#3
     }, [onClose, resetState]);
     return (react_1.default.createElement(react_native_1.View, { style: styles.container },
         screen === 'scanner' && (react_1.default.createElement(react_native_1.View, { style: styles.flex },
-            react_1.default.createElement(DocScanner_1.DocScanner, { autoCapture: !manualCapture, overlayColor: overlayColor, minStableFrames: minStableFrames ?? 6, detectionConfig: detectionConfig, onCapture: handleCapture },
+            react_1.default.createElement(DocScanner_1.DocScanner, { autoCapture: !manualCapture, overlayColor: overlayColor, showGrid: showGrid, gridColor: resolvedGridColor, gridLineWidth: gridLineWidth, minStableFrames: minStableFrames ?? 6, detectionConfig: detectionConfig, onCapture: handleCapture },
                 react_1.default.createElement(react_native_1.View, { style: styles.overlay, pointerEvents: "box-none" },
                     react_1.default.createElement(react_native_1.TouchableOpacity, { style: styles.closeButton, onPress: handleClose, accessibilityLabel: mergedStrings.cancel, accessibilityRole: "button" },
                         react_1.default.createElement(react_native_1.Text, { style: styles.closeButtonLabel }, "\u00D7")),

package/dist/index.d.ts

@@ -3,5 +3,5 @@ export { CropEditor } from './CropEditor';
 export { FullDocScanner } from './FullDocScanner';
 export type { FullDocScannerResult, FullDocScannerProps, FullDocScannerStrings, } from './FullDocScanner';
 export type { Point, Quad, Rectangle, CapturedDocument } from './types';
-export type { DetectionConfig } from './DocScanner';
+export type { DetectionConfig, DocScannerHandle } from './DocScanner';
 export { quadToRectangle, rectangleToQuad, scaleCoordinates, scaleRectangle, } from './utils/coordinate';

package/dist/utils/overlay.js

@@ -41,62 +41,91 @@ const lerp = (start, end, t) => ({
     x: start.x + (end.x - start.x) * t,
     y: start.y + (end.y - start.y) * t,
 });
+const withAlpha = (value, alpha) => {
+    const hexMatch = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(value.trim());
+    if (!hexMatch) {
+        return `rgba(231, 166, 73, ${alpha})`;
+    }
+    const hex = hexMatch[1];
+    const normalize = hex.length === 3
+        ? hex.split('').map((ch) => ch + ch).join('')
+        : hex;
+    const r = parseInt(normalize.slice(0, 2), 16);
+    const g = parseInt(normalize.slice(2, 4), 16);
+    const b = parseInt(normalize.slice(4, 6), 16);
+    return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+};
+const buildPath = (points) => {
+    const path = react_native_skia_1.Skia.Path.Make();
+    path.moveTo(points[0].x, points[0].y);
+    points.slice(1).forEach((p) => path.lineTo(p.x, p.y));
+    path.close();
+    return path;
+};
 const Overlay = ({ quad, color = '#e7a649', frameSize, showGrid = true, gridColor = 'rgba(231, 166, 73, 0.35)', gridLineWidth = 2, }) => {
     const { width: screenWidth, height: screenHeight } = (0, react_native_1.useWindowDimensions)();
+    const fillColor = (0, react_1.useMemo)(() => withAlpha(color, 0.2), [color]);
     const { outlinePath, gridPaths } = (0, react_1.useMemo)(() => {
-        if (!quad || !frameSize) {
-            if (__DEV__) {
-                console.log('[Overlay] no quad or frameSize', { quad, frameSize });
-            }
-            return { outlinePath: null, gridPaths: [] };
-        }
-        if (__DEV__) {
-            console.log('[Overlay] drawing quad:', quad);
-            console.log('[Overlay] color:', color);
-            console.log('[Overlay] screen dimensions:', screenWidth, 'x', screenHeight);
-            console.log('[Overlay] frame dimensions:', frameSize.width, 'x', frameSize.height);
+        let transformedQuad = null;
+        let sourceQuad = null;
+        let sourceFrameSize = frameSize;
+        if (quad && frameSize) {
+            sourceQuad = quad;
         }
-        // Check if camera is in landscape mode (width > height) but screen is portrait (height > width)
-        const isFrameLandscape = frameSize.width > frameSize.height;
-        const isScreenPortrait = screenHeight > screenWidth;
-        const needsRotation = isFrameLandscape && isScreenPortrait;
-        if (__DEV__) {
-            console.log('[Overlay] needs rotation:', needsRotation);
-        }
-        let transformedQuad;
-        if (needsRotation) {
-            // Camera is landscape, screen is portrait - need to rotate 90 degrees
-            // Transform: rotate 90° clockwise and scale
-            // New coordinates: x' = y * (screenWidth / frameHeight), y' = (frameWidth - x) * (screenHeight / frameWidth)
-            const scaleX = screenWidth / frameSize.height;
-            const scaleY = screenHeight / frameSize.width;
-            if (__DEV__) {
-                console.log('[Overlay] rotation scale factors:', scaleX, 'x', scaleY);
+        else {
+            const marginRatio = 0.12;
+            const marginX = screenWidth * marginRatio;
+            const marginY = screenHeight * marginRatio;
+            const maxWidth = screenWidth - marginX * 2;
+            const maxHeight = screenHeight - marginY * 2;
+            const a4Ratio = Math.SQRT2; // ~1.414 height / width
+            let width = maxWidth;
+            let height = width * a4Ratio;
+            if (height > maxHeight) {
+                height = maxHeight;
+                width = height / a4Ratio;
             }
-            transformedQuad = quad.map((p) => ({
-                x: p.y * scaleX,
-                y: (frameSize.width - p.x) * scaleY,
-            }));
+            const left = (screenWidth - width) / 2;
+            const top = (screenHeight - height) / 2;
+            transformedQuad = [
+                { x: left, y: top },
+                { x: left + width, y: top },
+                { x: left + width, y: top + height },
+                { x: left, y: top + height },
+            ];
+            sourceFrameSize = null;
         }
-        else {
-            // Same orientation - just scale
-            const scaleX = screenWidth / frameSize.width;
-            const scaleY = screenHeight / frameSize.height;
+        if (sourceQuad && sourceFrameSize) {
             if (__DEV__) {
-                console.log('[Overlay] scale factors:', scaleX, 'x', scaleY);
+                console.log('[Overlay] drawing quad:', sourceQuad);
+                console.log('[Overlay] color:', color);
+                console.log('[Overlay] screen dimensions:', screenWidth, 'x', screenHeight);
+                console.log('[Overlay] frame dimensions:', sourceFrameSize.width, 'x', sourceFrameSize.height);
+            }
+            const isFrameLandscape = sourceFrameSize.width > sourceFrameSize.height;
+            const isScreenPortrait = screenHeight > screenWidth;
+            const needsRotation = isFrameLandscape && isScreenPortrait;
+            if (needsRotation) {
+                const scaleX = screenWidth / sourceFrameSize.height;
+                const scaleY = screenHeight / sourceFrameSize.width;
+                transformedQuad = sourceQuad.map((p) => ({
+                    x: p.y * scaleX,
+                    y: (sourceFrameSize.width - p.x) * scaleY,
+                }));
+            }
+            else {
+                const scaleX = screenWidth / sourceFrameSize.width;
+                const scaleY = screenHeight / sourceFrameSize.height;
+                transformedQuad = sourceQuad.map((p) => ({
+                    x: p.x * scaleX,
+                    y: p.y * scaleY,
+                }));
             }
-            transformedQuad = quad.map((p) => ({
-                x: p.x * scaleX,
-                y: p.y * scaleY,
-            }));
         }
-        if (__DEV__) {
-            console.log('[Overlay] transformed quad:', transformedQuad);
+        if (!transformedQuad) {
+            return { outlinePath: null, gridPaths: [] };
         }
-        const skPath = react_native_skia_1.Skia.Path.Make();
-        skPath.moveTo(transformedQuad[0].x, transformedQuad[0].y);
-        transformedQuad.slice(1).forEach((p) => skPath.lineTo(p.x, p.y));
-        skPath.close();
+        const skPath = buildPath(transformedQuad);
         const grid = [];
         if (showGrid) {
             const [topLeft, topRight, bottomRight, bottomLeft] = transformedQuad;
@@ -119,14 +148,14 @@ const Overlay = ({ quad, color = '#e7a649', frameSize, showGrid = true, gridColo
             });
         }
         return { outlinePath: skPath, gridPaths: grid };
-    }, [quad, screenWidth, screenHeight, frameSize, showGrid]);
+    }, [quad, screenWidth, screenHeight, frameSize, showGrid, color]);
     if (__DEV__) {
         console.log('[Overlay] rendering Canvas with dimensions:', screenWidth, 'x', screenHeight);
     }
     return (react_1.default.createElement(react_native_1.View, { style: styles.container, pointerEvents: "none" },
         react_1.default.createElement(react_native_skia_1.Canvas, { style: { width: screenWidth, height: screenHeight } }, outlinePath && (react_1.default.createElement(react_1.default.Fragment, null,
             react_1.default.createElement(react_native_skia_1.Path, { path: outlinePath, color: color, style: "stroke", strokeWidth: 8 }),
-            react_1.default.createElement(react_native_skia_1.Path, { path: outlinePath, color: "rgba(231, 166, 73, 0.2)", style: "fill" }),
+            react_1.default.createElement(react_native_skia_1.Path, { path: outlinePath, color: fillColor, style: "fill" }),
             gridPaths.map((gridPath, index) => (react_1.default.createElement(react_native_skia_1.Path
             // eslint-disable-next-line react/no-array-index-key
             , { 

package/docs/native-module-architecture.md

@@ -0,0 +1,178 @@
+# Native Module Architecture Plan
+
+This document lays out the roadmap for migrating the library from its current
+VisionCamera/OpenCV implementation to a fully native document scanner module
+that mirrors the behaviour of `react-native-document-scanner-plugin` while
+keeping support for custom React components and overlays.
+
+## Goals
+
+- Expose a `<DocScanner />` React view component that renders a native camera
+  preview.
+- Maintain the ability to layer custom React children (buttons, hints, headers)
+  on top of the preview.
+- Provide the detected polygon and stability information every frame, so the
+  existing Skia overlay and auto-capture logic continue working.
+- Support both automatic and manual capture flows; captures should resolve with
+  both cropped and original image metadata.
+- Keep the public TypeScript API as close as possible to the current version to
+  minimise breaking changes for consuming apps.
+
+## High-Level Architecture
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│ React Native (TypeScript)                                            │
+│ ┌────────────────────────────┐   events / commands   ┌─────────────┐ │
+│ │ DocScanner.tsx (wrapper)  ├───────────────────────▶│ Native View │ │
+│ │ - Manages refs            │◀───────────────────────┤  Module     │ │
+│ │ - Handles props           │   layout callbacks     └─────────────┘ │
+│ │ - Renders Overlay + UI    │                                        │
+│ └────────────────────────────┘                                        │
+│                ▲                             ▲                       │
+│                │onRectangleDetect            │onPictureTaken         │
+└────────────────┴─────────────────────────────┴───────────────────────┘
+                 │                             │
+        ┌────────┴────────┐             ┌──────┴──────┐
+        │ iOS (Swift)      │             │ Android     │
+        │ DocScannerView   │             │ DocScannerView │
+        │ - AVCapture      │             │ - CameraX       │
+        │ - Vision / VNDetectRectangles │ │ - ML Kit / OpenCV│
+        │ - VNDocumentCamera for capture ││ - On-device cropping │
+        └──────────────────┘             └───────────────────────┘
+```
+
+### React Native Layer
+
+- `DocScanner.tsx`
+  - Forwards props to the native view via `requireNativeComponent`.
+  - Holds a ref to call `capture()`, `setTorchEnabled()`, etc.
+  - Converts native events into the existing `Point[]` / stability format.
+  - Continues rendering the Skia-based `Overlay` and any child components.
+- `index.ts`
+  - Exports the wrapper and new types.
+- TypeScript definitions for native events, capture result, and imperative
+  methods (`DocScannerHandle`).
+
+### iOS Implementation
+
+- Create `ios/DocScannerView.swift`
+  - Subclass of `UIView` hosting an `AVCaptureVideoPreviewLayer`.
+  - Uses `AVCaptureSession` with `AVCaptureVideoDataOutput` to stream frames.
+  - Runs `VNDetectRectanglesRequest` on a background queue for polygon
+    detection.
+  - Emits `onRectangleDetect` events (containing points, stability counter, and
+    frame size) via `RCTDirectEventBlock`.
+  - Implements `capture()` by calling `AVCapturePhotoOutput` and optionally
+    running `CIFilter` warps for perspective correction.
+  - Saves both original and cropped images, returning their URIs plus width /
+    height.
+
+- Create `ios/DocScannerViewManager.m`
+  - Registers the component as `RNRDocScannerView` (name to be decided).
+  - Exposes props: `overlayColor`, `detectionCountBeforeCapture`, `torchEnabled`,
+    `useBase64`, `quality`, etc.
+  - Exposes commands / methods: `capture`, `setTorchEnabled`, `reset`.
+
+- Create backing Swift files:
+  - `DocScannerFrameProcessor.swift` – handles rectangle detection and stability
+    scoring.
+  - `DocScannerCaptureCoordinator.swift` – manages photo output, perspective
+    correction, optional VisionKit integration.
+  - `DocScannerEventPayload.swift` – strongly typed event payloads.
+
+### Android Implementation
+
+- Create `android/src/main/java/.../DocScannerView.kt`
+  - Extends `FrameLayout`, hosts a `PreviewView` from CameraX.
+  - Sets up `ProcessCameraProvider` with `ImageAnalysis` for frame processing.
+  - Runs ML Kit Document Scanner API (or OpenCV fallback) to detect quads.
+  - Emits events through `@ReactProp` + `UIManagerModule` event dispatch.
+  - Maintains stability counter similar to current JS implementation.
+
+- Create `DocScannerViewManager.kt`
+  - Registers the view name (e.g. `RNRDocScannerView`).
+  - Maps props (`overlayColor`, `detectionCountBeforeCapture`, etc.).
+  - Implements `receiveCommand` to handle `capture`, `torch`, `reset`.
+
+- Create `DocScannerModule.kt`
+  - Exposes imperative methods if needed for non-view functionality (e.g. file
+    cleanup).
+
+- Provide utility classes:
+  - `ImageCropper.kt` – applies perspective transformations using OpenCV or
+    RenderScript.
+  - `PathUtils.kt` – file management for temporary images.
+  - `RectangleEvent.kt` – serialisable event payload.
+
+### Event Contract
+
+`onRectangleDetect` event shape (identical for iOS & Android):
+
+```ts
+type RectangleEventPayload = {
+  rectangleCoordinates: {
+    topLeft: Point;
+    topRight: Point;
+    bottomRight: Point;
+    bottomLeft: Point;
+  } | null;
+  stableCounter: number;
+  frameWidth: number;
+  frameHeight: number;
+};
+```
+
+`onPictureTaken` event shape:
+
+```ts
+type PictureEvent = {
+  croppedImage: string | null; // file:// or base64 depending on props
+  initialImage: string;
+  width: number;
+  height: number;
+};
+```
+
+### Props Mapping
+
+| Prop                          | Description                                         | Native handling                       |
+|-------------------------------|-----------------------------------------------------|---------------------------------------|
+| `overlayColor`               | Stroke colour for overlay (forwarded to events)     | Only metadata – actual overlay is JS  |
+| `detectionCountBeforeCapture`| Minimum stable frames before auto capture           | Native stability counter              |
+| `autoCapture`                | If `true`, native triggers capture automatically    | Native triggers `capture()` internally|
+| `enableTorch`                | Controls device torch                               | Maps to `AVCaptureDevice` / CameraX   |
+| `quality`                    | JPEG quality (0–100)                                | Controls compression in native capture|
+| `useBase64`                  | If `true`, return base64 strings instead of files   | Native encode                          |
+| `showGrid`, `gridColor`...   | Handled in JS overlay; no native changes required   | N/A                                   |
+
+### Migration Steps
+
+1. **Scaffold native module directories**
+   - Add `ios/` and `android/` folders with minimal React Native module wiring.
+
+2. **Implement iOS detection & capture**
+   - Set up camera session, rectangle detection, event dispatch.
+   - Support auto capture and manual capture commands.
+
+3. **Implement Android detection & capture**
+   - Mirror iOS logic with CameraX + ML Kit/OpenCV.
+
+4. **Update TypeScript wrapper**
+   - Replace VisionCamera/OpenCV logic with `requireNativeComponent`.
+   - Keep existing overlay and UI contract intact.
+
+5. **Testing & validation**
+   - Write example app update (outside this package) to verify events, overlay,
+    auto-capture.
+   - Ensure TypeScript typings align with native behaviour.
+
+6. **Documentation**
+   - Update README with new installation instructions (pods/gradle changes,
+    permissions, peer deps).
+   - Document new props & events, auto/manual capture behaviour.
+
+This plan focuses on creating a native module while preserving the custom
+overlay UX. Each platform will require significant native code, but the above
+structure provides the blueprint for implementation.
+

package/ios/RNRDocScannerModule.swift

@@ -0,0 +1,49 @@
+import Foundation
+import React
+
+@objc(RNRDocScannerModule)
+class RNRDocScannerModule: NSObject, RCTBridgeModule {
+  static func moduleName() -> String! {
+    "RNRDocScannerModule"
+  }
+
+  static func requiresMainQueueSetup() -> Bool {
+    true
+  }
+
+  @objc var bridge: RCTBridge?
+
+  @objc func capture(_ reactTag: NSNumber, resolver resolve: @escaping RCTPromiseResolveBlock, rejecter reject: @escaping RCTPromiseRejectBlock) {
+    bridge?.uiManager?.addUIBlock { _, viewRegistry in
+      guard let view = viewRegistry?[reactTag] as? RNRDocScannerView else {
+        reject(RNRDocScannerError.viewNotFound.code, RNRDocScannerError.viewNotFound.message, nil)
+        return
+      }
+
+      view.capture { result in
+        switch result {
+        case let .success(payload):
+          resolve([
+            "croppedImage": payload.croppedImage as Any,
+            "initialImage": payload.originalImage,
+            "width": payload.width,
+            "height": payload.height,
+          ])
+        case let .failure(error as RNRDocScannerError):
+          reject(error.code, error.message, error)
+        case let .failure(error):
+          reject("capture_failed", error.localizedDescription, error)
+        }
+      }
+    }
+  }
+
+  @objc func reset(_ reactTag: NSNumber) {
+    bridge?.uiManager?.addUIBlock { _, viewRegistry in
+      guard let view = viewRegistry?[reactTag] as? RNRDocScannerView else {
+        return
+      }
+      view.resetStability()
+    }
+  }
+}