@jaak.ai/stamps 2.0.0-dev.53 → 2.0.0-dev.55

package/README.md

@@ -1,611 +1,761 @@
-# Jaak Stamps - Document Detector Web Component
+# Jaak Stamps Web Component
 
-A web component for automatic detection and capture of identification documents using computer vision.
+[![npm version](https://badge.fury.io/js/%40jaak.ai%2Fstamps.svg)](https://www.npmjs.com/package/@jaak.ai/stamps)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Features
+[📖 Versión en Español](./README_ES.md)
 
-- Real-time automatic document detection
-- Visual guide for optimal document positioning
-- Intelligent document classification to determine if back capture is required
-- Adaptive capture - automatically detects if document requires back side
-- Dual output for each side: full frame and cropped document
-- Configurable cropping with customizable margin around document
-- Programmatic API for complete process control
-- Responsive and mobile device compatible
-- Automatic optimization for better performance
+## Description
+
+Jaak Stamps is a powerful web component for document scanning and capture using camera input with AI-powered document detection. The component provides a complete solution for capturing high-quality document images with real-time detection feedback and automated cropping capabilities.
+
+### Key Features
+
+- **AI-Powered Document Detection**: Automatically detects and frames documents in the camera view
+- **Dual-Side Capture**: Supports both front and back document capture workflow
+- **Real-time Preview**: Live camera feed with detection overlays and guidance
+- **Multi-Camera Support**: Automatic camera selection with manual override options
+- **Smart Cropping**: Automatic document boundary detection and cropping
+- **Mobile Optimized**: Responsive design that works across all device sizes
+- **Web Standards Compliant**: Built as a standard Web Component for maximum compatibility
+
+### Typical Use Cases
+
+- **Identity Verification**: Capture ID cards, passports, and driver's licenses
+- **Document Digitization**: Scan contracts, certificates, and legal documents  
+- **KYC/AML Processes**: Streamlined identity document capture for compliance
+- **Form Processing**: Digitize paper forms and applications
+- **Insurance Claims**: Capture damage reports and supporting documentation
 
 ## Installation
 
-### NPM
+### NPM/Yarn
+
 ```bash
+# Using npm
 npm install @jaak.ai/stamps
-```
 
-### Yarn
-```bash
+# Using yarn
 yarn add @jaak.ai/stamps
 ```
 
 ### CDN
+
 ```html
+<!-- ES Module -->
 <script type="module" src="https://unpkg.com/@jaak.ai/stamps/dist/jaak-stamps-webcomponent/jaak-stamps-webcomponent.esm.js"></script>
+
+<!-- With Loader -->
+<script type="module">
+  import { defineCustomElements } from 'https://unpkg.com/@jaak.ai/stamps/loader/index.js';
+  defineCustomElements();
+</script>
+```
+
+## API Reference
+
+### Properties/Attributes
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `debug` | `boolean` | `false` | Enable debug mode with additional logging and overlays |
+| `mask-size` | `number` | `80` | Size percentage of the document detection mask |
+| `alignment-tolerance` | `number` | `15` | Tolerance level for document alignment detection |
+| `capture-delay` | `number` | `1500` | Delay in milliseconds before automatic capture |
+| `crop-margin` | `number` | `20` | Margin in pixels around detected document for cropping |
+| `preferred-camera` | `'auto' \| 'front' \| 'back'` | `'auto'` | Preferred camera selection |
+| `use-document-classification` | `boolean` | `false` | Enable AI document classification |
+| `enable-back-document-timer` | `boolean` | `false` | Enable timer for back document capture |
+| `back-document-timer-duration` | `number` | `20` | Duration in seconds for back document capture timer |
+
+### Methods
+
+#### Camera Control
+
+```typescript
+// Get information about available cameras
+getCameraInfo(): Promise<CameraInfoResponse>
+
+// Set preferred camera
+setPreferredCamera(camera: "auto" | "front" | "back"): Promise<{
+  success: boolean;
+  selectedCamera: string;
+  availableCameras: number;
+}>
+
+// Control device torch/flashlight
+setTorchEnabled(enabled: boolean): Promise<{
+  success: boolean;
+  enabled: boolean;
+}>
+
+// Focus camera at specific point
+focusAtPoint(x: number, y: number): Promise<{
+  success: boolean;
+  coordinates: { x: number; y: number };
+}>
 ```
 
-## Basic Usage
+#### Capture Control
+
+```typescript
+// Start the capture process
+startCapture(): Promise<void>
+
+// Stop the capture process
+stopCapture(): Promise<void>
+
+// Reset capture state
+resetCapture(): Promise<void>
 
-### HTML Vanilla
+// Skip back document capture
+skipBackCapture(): Promise<void>
+```
+
+#### Configuration
+
+```typescript
+// Set capture delay
+setCaptureDelay(delay: number): Promise<{
+  success: boolean;
+  captureDelay: number;
+}>
+
+// Get current capture delay
+getCaptureDelay(): Promise<number>
+```
+
+#### Status & Data
+
+```typescript
+// Get current component status
+getStatus(): Promise<StatusResponse>
+
+// Get captured images
+getCapturedImages(): Promise<CapturedImagesResponse>
+
+// Check if process is completed
+isProcessCompleted(): Promise<boolean>
+
+// Preload AI model
+preloadModel(): Promise<{
+  success: boolean;
+  message?: string;
+  error?: any;
+}>
+```
+
+### Events
+
+| Event | Detail Type | Description |
+|-------|-------------|-------------|
+| `isReady` | `boolean` | Fired when component is fully initialized and ready |
+| `captureCompleted` | `object` | Fired when document capture process is completed |
+
+### Type Definitions
+
+```typescript
+interface CameraInfoResponse {
+  availableCameras: Array<{
+    id: string;
+    label: string;
+    selected: boolean;
+  }>;
+  selectedCameraId: string | null;
+  deviceType: string;
+  isMultipleCamerasAvailable: boolean;
+  preferredFacing: 'environment' | 'user' | null;
+}
+
+interface CapturedImagesResponse {
+  front: {
+    fullFrame: string | null;
+    cropped: string | null;
+  };
+  back: {
+    fullFrame: string | null;
+    cropped: string | null;
+  };
+  metadata: {
+    totalImages: number;
+    processCompleted: boolean;
+    backCaptureSkipped: boolean;
+  };
+}
+
+interface StatusResponse {
+  isVideoActive: boolean;
+  captureStep: 'front' | 'back' | 'completed';
+  hasImages: boolean;
+  isProcessCompleted: boolean;
+  isModelPreloaded: boolean;
+}
+```
+
+## Implementation Examples
+
+### Vanilla JavaScript
 
 ```html
 <!DOCTYPE html>
 <html>
 <head>
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <script type="module" src="https://unpkg.com/@jaak.ai/stamps/dist/jaak-stamps-webcomponent/jaak-stamps-webcomponent.esm.js"></script>
+  <script type="module" src="https://unpkg.com/@jaak.ai/stamps/dist/jaak-stamps-webcomponent/jaak-stamps-webcomponent.esm.js"></script>
 </head>
 <body>
-    <jaak-stamps id="detector" debug="false" mask-size="80" crop-margin="20" capture-delay="1000" use-document-classification="false"></jaak-stamps>
+  <jaak-stamps
+    id="documentScanner"
+    preferred-camera="auto"
+    capture-delay="1500"
+    debug="false">
+  </jaak-stamps>
+
+  <script>
+    const scanner = document.getElementById('documentScanner');
     
-    <button onclick="startCapture()">Start Capture</button>
-    <button onclick="stopCapture()">Stop</button>
-    <button onclick="resetCapture()">Reset</button>
-
-    <script>
-        const detector = document.getElementById('detector');
-        
-        // Listen for capture completed event
-        detector.addEventListener('captureCompleted', (event) => {
-            console.log('Capture completed:', event.detail);
-            // event.detail contains the captured images
-        });
-        
-        // Listen for component ready event
-        detector.addEventListener('isReady', (event) => {
-            console.log('Component ready:', event.detail);
-            // event.detail indicates if the component is ready (true/false)
-        });
-        
-        function startCapture() {
-            detector.startCapture();
-        }
-        
-        function stopCapture() {
-            detector.stopCapture();
-        }
-        
-        function resetCapture() {
-            detector.resetCapture();
-        }
-        
-        // Preload model (optional - improves performance)
-        async function preloadModel() {
-            try {
-                const result = await detector.preloadModel();
-                console.log('Model preloaded:', result);
-            } catch (error) {
-                console.error('Error preloading:', error);
-            }
-        }
-        
-        // Get images after capture
-        async function getImages() {
-            try {
-                const images = await detector.getCapturedImages();
-                console.log('Captured images:', images);
-            } catch (error) {
-                console.error('Error:', error.message);
-            }
-        }
-    </script>
+    // Wait for component to be ready
+    scanner.addEventListener('isReady', () => {
+      console.log('Document scanner is ready');
+      
+      // Start the capture process
+      scanner.startCapture();
+    });
+    
+    // Handle capture completion
+    scanner.addEventListener('captureCompleted', async (event) => {
+      console.log('Capture completed:', event.detail);
+      
+      // Get captured images
+      const images = await scanner.getCapturedImages();
+      console.log('Captured images:', images);
+      
+      // Process the images as needed
+      if (images.front.cropped) {
+        // Display or upload the cropped front image
+        displayImage(images.front.cropped);
+      }
+    });
+    
+    function displayImage(base64Image) {
+      const img = document.createElement('img');
+      img.src = `data:image/jpeg;base64,${base64Image}`;
+      document.body.appendChild(img);
+    }
+  </script>
 </body>
 </html>
 ```
 
-### Angular
+### React
 
-#### 1. Install the component
-```bash
-npm install @jaak.ai/stamps
-```
+```tsx
+import React, { useEffect, useRef, useState } from 'react';
+import { defineCustomElements } from '@jaak.ai/stamps/loader';
 
-#### 2. Configure the module (app.module.ts)
-```typescript
-import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
-import { BrowserModule } from '@angular/platform-browser';
-import { AppComponent } from './app.component';
+// Define custom elements
+defineCustomElements();
+
+// Extend HTMLElement for TypeScript
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      'jaak-stamps': any;
+    }
+  }
+}
 
-// Import the web component
-import '@jaak.ai/stamps/dist/jaak-stamps-webcomponent/jaak-stamps-webcomponent.esm.js';
+interface CapturedImages {
+  front: { fullFrame: string | null; cropped: string | null };
+  back: { fullFrame: string | null; cropped: string | null };
+  metadata: {
+    totalImages: number;
+    processCompleted: boolean;
+    backCaptureSkipped: boolean;
+  };
+}
 
-@NgModule({
-  declarations: [AppComponent],
-  imports: [BrowserModule],
-  providers: [],
-  bootstrap: [AppComponent],
-  schemas: [CUSTOM_ELEMENTS_SCHEMA] // Allow custom elements
-})
-export class AppModule { }
+const DocumentScanner: React.FC = () => {
+  const scannerRef = useRef<HTMLElement>(null);
+  const [isReady, setIsReady] = useState(false);
+  const [capturedImages, setCapturedImages] = useState<CapturedImages | null>(null);
+  
+  useEffect(() => {
+    const scanner = scannerRef.current;
+    if (!scanner) return;
+    
+    // Component ready handler
+    const handleReady = () => {
+      setIsReady(true);
+    };
+    
+    // Capture completion handler
+    const handleCaptureCompleted = async () => {
+      const images = await (scanner as any).getCapturedImages();
+      setCapturedImages(images);
+    };
+    
+    // Add event listeners
+    scanner.addEventListener('isReady', handleReady);
+    scanner.addEventListener('captureCompleted', handleCaptureCompleted);
+    
+    return () => {
+      scanner.removeEventListener('isReady', handleReady);
+      scanner.removeEventListener('captureCompleted', handleCaptureCompleted);
+    };
+  }, []);
+  
+  const startScan = async () => {
+    if (scannerRef.current) {
+      await (scannerRef.current as any).startCapture();
+    }
+  };
+  
+  return (
+    <div>
+      <h2>Document Scanner</h2>
+      
+      <jaak-stamps
+        ref={scannerRef}
+        preferred-camera="auto"
+        capture-delay={1500}
+        use-document-classification={true}
+      />
+      
+      <div style={{ marginTop: '20px' }}>
+        <button onClick={startScan} disabled={!isReady}>
+          {isReady ? 'Start Scanning' : 'Loading...'}
+        </button>
+      </div>
+      
+      {capturedImages && (
+        <div style={{ marginTop: '20px' }}>
+          <h3>Captured Images</h3>
+          {capturedImages.front.cropped && (
+            <div>
+              <h4>Front Document</h4>
+              <img 
+                src={`data:image/jpeg;base64,${capturedImages.front.cropped}`}
+                alt="Front document"
+                style={{ maxWidth: '300px' }}
+              />
+            </div>
+          )}
+          {capturedImages.back.cropped && (
+            <div>
+              <h4>Back Document</h4>
+              <img 
+                src={`data:image/jpeg;base64,${capturedImages.back.cropped}`}
+                alt="Back document"
+                style={{ maxWidth: '300px' }}
+              />
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default DocumentScanner;
 ```
 
-#### 3. Use in the component
+### Angular
+
 ```typescript
-// app.component.ts
-import { Component, ElementRef, ViewChild, OnInit } from '@angular/core';
+// document-scanner.component.ts
+import { Component, ElementRef, ViewChild, AfterViewInit, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+import { defineCustomElements } from '@jaak.ai/stamps/loader';
+
+// Define custom elements
+defineCustomElements();
+
+interface CapturedImages {
+  front: { fullFrame: string | null; cropped: string | null };
+  back: { fullFrame: string | null; cropped: string | null };
+  metadata: {
+    totalImages: number;
+    processCompleted: boolean;
+    backCaptureSkipped: boolean;
+  };
+}
 
 @Component({
-  selector: 'app-root',
+  selector: 'app-document-scanner',
   template: `
-    <div class="container">
-      <h1>Document Detector</h1>
+    <div class="scanner-container">
+      <h2>Document Scanner</h2>
       
-      <jaak-stamps 
-        #detector
-        [debug]="false"
-        [maskSize]="80"
-        [cropMargin]="20"
-        [useDocumentClassification]="false"
-        (captureCompleted)="onCaptureCompleted($event)"
-        (isReady)="onComponentReady($event)">
+      <jaak-stamps
+        #scanner
+        preferred-camera="auto"
+        [capture-delay]="1500"
+        [use-document-classification]="true">
       </jaak-stamps>
       
       <div class="controls">
-        <button (click)="preloadModel()">Preload Model</button>
-        <button (click)="startCapture()">Start Capture</button>
-        <button (click)="stopCapture()">Stop</button>
-        <button (click)="resetCapture()">Reset</button>
-        <button (click)="getImages()" [disabled]="!isCompleted">Get Images</button>
+        <button 
+          (click)="startScan()" 
+          [disabled]="!isReady"
+          class="scan-button">
+          {{ isReady ? 'Start Scanning' : 'Loading...' }}
+        </button>
+        
+        <button 
+          (click)="resetScan()" 
+          [disabled]="!isReady"
+          class="reset-button">
+          Reset
+        </button>
       </div>
       
-      <div *ngIf="capturedData" class="results">
-        <h3>Captured Images:</h3>
-        <p>Total images: {{ capturedData.metadata.totalImages }}</p>
-        <img *ngIf="capturedData.front.cropped" [src]="capturedData.front.cropped" alt="Front">
-        <img *ngIf="capturedData.back.cropped" [src]="capturedData.back.cropped" alt="Back">
+      <div *ngIf="capturedImages" class="results">
+        <h3>Captured Images</h3>
+        
+        <div *ngIf="capturedImages.front.cropped" class="image-result">
+          <h4>Front Document</h4>
+          <img 
+            [src]="'data:image/jpeg;base64,' + capturedImages.front.cropped"
+            alt="Front document"
+            class="captured-image">
+        </div>
+        
+        <div *ngIf="capturedImages.back.cropped" class="image-result">
+          <h4>Back Document</h4>
+          <img 
+            [src]="'data:image/jpeg;base64,' + capturedImages.back.cropped"
+            alt="Back document"
+            class="captured-image">
+        </div>
+        
+        <div class="metadata">
+          <p>Total Images: {{ capturedImages.metadata.totalImages }}</p>
+          <p>Process Completed: {{ capturedImages.metadata.processCompleted }}</p>
+        </div>
       </div>
     </div>
   `,
   styles: [`
-    .container { max-width: 800px; margin: 0 auto; padding: 20px; }
-    .controls { margin: 20px 0; }
-    .controls button { margin: 0 10px; padding: 10px 20px; }
-    .results img { max-width: 300px; margin: 10px; border: 1px solid #ccc; }
-  `]
-})
-export class AppComponent implements OnInit {
-  @ViewChild('detector', { static: true }) detectorRef!: ElementRef;
-  
-  capturedData: any = null;
-  isCompleted = false;
-  
-  ngOnInit() {
-    // The element is already available after the view
-  }
-  
-  async preloadModel() {
-    try {
-      const result = await this.detectorRef.nativeElement.preloadModel();
-      console.log('Model preloaded:', result);
-    } catch (error) {
-      console.error('Error preloading model:', error);
+    .scanner-container {
+      max-width: 600px;
+      margin: 0 auto;
+      padding: 20px;
     }
-  }
-
-  async startCapture() {
-    try {
-      await this.detectorRef.nativeElement.startCapture();
-    } catch (error) {
-      console.error('Error starting capture:', error);
+    
+    .controls {
+      margin: 20px 0;
+      display: flex;
+      gap: 10px;
     }
-  }
+    
+    .scan-button, .reset-button {
+      padding: 10px 20px;
+      font-size: 16px;
+      border: none;
+      border-radius: 4px;
+      cursor: pointer;
+    }
+    
+    .scan-button {
+      background-color: #007bff;
+      color: white;
+    }
+    
+    .reset-button {
+      background-color: #6c757d;
+      color: white;
+    }
+    
+    .scan-button:disabled, .reset-button:disabled {
+      opacity: 0.6;
+      cursor: not-allowed;
+    }
+    
+    .results {
+      margin-top: 20px;
+    }
+    
+    .image-result {
+      margin: 20px 0;
+    }
+    
+    .captured-image {
+      max-width: 100%;
+      height: auto;
+      border: 1px solid #ddd;
+      border-radius: 4px;
+    }
+    
+    .metadata {
+      background-color: #f8f9fa;
+      padding: 10px;
+      border-radius: 4px;
+      margin-top: 20px;
+    }
+  `],
+  schemas: [CUSTOM_ELEMENTS_SCHEMA]
+})
+export class DocumentScannerComponent implements AfterViewInit {
+  @ViewChild('scanner', { static: false }) scannerRef!: ElementRef;
   
-  async stopCapture() {
-    await this.detectorRef.nativeElement.stopCapture();
-  }
+  isReady = false;
+  capturedImages: CapturedImages | null = null;
   
-  async resetCapture() {
-    await this.detectorRef.nativeElement.resetCapture();
-    this.capturedData = null;
-    this.isCompleted = false;
+  ngAfterViewInit() {
+    const scanner = this.scannerRef.nativeElement;
+    
+    // Component ready handler
+    scanner.addEventListener('isReady', () => {
+      this.isReady = true;
+    });
+    
+    // Capture completion handler
+    scanner.addEventListener('captureCompleted', async () => {
+      this.capturedImages = await scanner.getCapturedImages();
+    });
   }
   
-  async getImages() {
-    try {
-      const images = await this.detectorRef.nativeElement.getCapturedImages();
-      console.log('Images obtained:', images);
-    } catch (error) {
-      console.error('Error getting images:', error);
+  async startScan() {
+    if (this.scannerRef?.nativeElement) {
+      await this.scannerRef.nativeElement.startCapture();
     }
   }
   
-  onCaptureCompleted(event: any) {
-    console.log('Capture completed in Angular:', event.detail);
-    this.capturedData = event.detail;
-    this.isCompleted = true;
-  }
-  
-  onComponentReady(event: any) {
-    console.log('Component ready in Angular:', event.detail);
-    // The component is ready to start detection
+  async resetScan() {
+    if (this.scannerRef?.nativeElement) {
+      await this.scannerRef.nativeElement.resetCapture();
+      this.capturedImages = null;
+    }
   }
 }
 ```
 
-### React
+```typescript
+// app.module.ts
+import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+import { BrowserModule } from '@angular/platform-browser';
+import { DocumentScannerComponent } from './document-scanner.component';
 
-#### 1. Install the component
-```bash
-npm install @jaak.ai/stamps
+@NgModule({
+  declarations: [DocumentScannerComponent],
+  imports: [BrowserModule],
+  schemas: [CUSTOM_ELEMENTS_SCHEMA], // Required for custom elements
+  exports: [DocumentScannerComponent]
+})
+export class DocumentScannerModule { }
 ```
 
-#### 2. Create wrapper component (optional but recommended)
-```jsx
-// JaakStampsWrapper.jsx
-import React, { useRef, useEffect, useImperativeHandle, forwardRef } from 'react';
+## Style Guide
+
+### CSS Custom Properties
 
-// Import the web component
-import '@jaak.ai/stamps/dist/jaak-stamps-webcomponent/jaak-stamps-webcomponent.esm.js';
+The component supports customization through CSS custom properties:
 
-const JaakStampsWrapper = forwardRef(({ debug = false, maskSize = 80, cropMargin = 20, useDocumentClassification = false, onCaptureCompleted, onIsReady }, ref) => {
-  const elementRef = useRef(null);
+```css
+jaak-stamps {
+  /* Camera view dimensions */
+  --camera-width: 100%;
+  --camera-height: 400px;
   
-  useImperativeHandle(ref, () => ({
-    preloadModel: () => elementRef.current?.preloadModel(),
-    startCapture: () => elementRef.current?.startCapture(),
-    stopCapture: () => elementRef.current?.stopCapture(),
-    resetCapture: () => elementRef.current?.resetCapture(),
-    getCapturedImages: () => elementRef.current?.getCapturedImages(),
-    getStatus: () => elementRef.current?.getStatus(),
-    skipBackCapture: () => elementRef.current?.skipBackCapture(),
-    isProcessCompleted: () => elementRef.current?.isProcessCompleted()
-  }));
+  /* Detection overlay colors */
+  --detection-overlay-color: rgba(0, 123, 255, 0.3);
+  --detection-border-color: #007bff;
+  --detection-border-width: 2px;
   
-  useEffect(() => {
-    const element = elementRef.current;
-    
-    const handleCaptureCompleted = (event) => {
-      if (onCaptureCompleted) {
-        onCaptureCompleted(event.detail);
-      }
-    };
-    
-    const handleIsReady = (event) => {
-      if (onIsReady) {
-        onIsReady(event.detail);
-      }
-    };
-    
-    if (element) {
-      element.addEventListener('captureCompleted', handleCaptureCompleted);
-      element.addEventListener('isReady', handleIsReady);
-      
-      return () => {
-        element.removeEventListener('captureCompleted', handleCaptureCompleted);
-        element.removeEventListener('isReady', handleIsReady);
-      };
-    }
-  }, [onCaptureCompleted, onIsReady]);
+  /* UI element colors */
+  --button-background: #007bff;
+  --button-text-color: #ffffff;
+  --button-border-radius: 4px;
   
-  return (
-    <jaak-stamps 
-      ref={elementRef} 
-      debug={debug}
-      mask-size={maskSize}
-      crop-margin={cropMargin}
-      use-document-classification={useDocumentClassification}
-    />
-  );
-});
+  /* Status indicator colors */
+  --status-success-color: #28a745;
+  --status-warning-color: #ffc107;
+  --status-error-color: #dc3545;
+}
+```
 
-export default JaakStampsWrapper;
+### Custom CSS Classes
+
+You can style the component container and add custom overlays:
+
+```css
+/* Component container styling */
+.document-scanner-container {
+  position: relative;
+  border: 1px solid #ddd;
+  border-radius: 8px;
+  overflow: hidden;
+  background: #000;
+}
+
+/* Custom loading overlay */
+.scanner-loading {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  background: rgba(0, 0, 0, 0.8);
+  color: white;
+  padding: 20px;
+  border-radius: 8px;
+  z-index: 1000;
+}
+
+/* Responsive design */
+@media (max-width: 768px) {
+  jaak-stamps {
+    --camera-height: 300px;
+  }
+}
 ```
 
-#### 3. Use in your React application
-```jsx
-// App.jsx
-import React, { useRef, useState } from 'react';
-import JaakStampsWrapper from './components/JaakStampsWrapper';
-
-function App() {
-  const detectorRef = useRef(null);
-  const [capturedData, setCapturedData] = useState(null);
-  const [isCompleted, setIsCompleted] = useState(false);
-  const [status, setStatus] = useState(null);
-  
-  const handleCaptureCompleted = (data) => {
-    console.log('Capture completed:', data);
-    setCapturedData(data);
-    setIsCompleted(true);
-  };
-  
-  const handleIsReady = (isReady) => {
-    console.log('Component ready:', isReady);
-    // The component is ready to start detection
-  };
-  
-  const preloadModel = async () => {
-    try {
-      const result = await detectorRef.current?.preloadModel();
-      console.log('Model preloaded:', result);
-    } catch (error) {
-      console.error('Error preloading model:', error);
-    }
-  };
-  
-  const startCapture = async () => {
-    try {
-      await detectorRef.current?.startCapture();
-    } catch (error) {
-      console.error('Error starting capture:', error);
-    }
-  };
-  
-  const stopCapture = async () => {
-    await detectorRef.current?.stopCapture();
-  };
-  
-  const resetCapture = async () => {
-    await detectorRef.current?.resetCapture();
-    setCapturedData(null);
-    setIsCompleted(false);
-  };
-  
-  const getImages = async () => {
-    try {
-      const images = await detectorRef.current?.getCapturedImages();
-      console.log('Images obtained:', images);
-    } catch (error) {
-      console.error('Error getting images:', error);
-    }
-  };
-  
-  const checkStatus = async () => {
-    const currentStatus = await detectorRef.current?.getStatus();
-    setStatus(currentStatus);
-  };
-  
-  return (
-    <div className="App">
-      <header className="App-header">
-        <h1>Document Detector - React</h1>
-        
-        <JaakStampsWrapper 
-          ref={detectorRef}
-          debug={false}
-          maskSize={80}
-          cropMargin={20}
-          useDocumentClassification={false}
-          onCaptureCompleted={handleCaptureCompleted}
-          onIsReady={handleIsReady}
-        />
-        
-        <div className="controls">
-          <button onClick={preloadModel}>Preload Model</button>
-          <button onClick={startCapture}>Start Capture</button>
-          <button onClick={stopCapture}>Stop</button>
-          <button onClick={resetCapture}>Reset</button>
-          <button onClick={getImages} disabled={!isCompleted}>
-            Get Images
-          </button>
-          <button onClick={checkStatus}>Check Status</button>
-        </div>
-        
-        {status && (
-          <div className="status">
-            <h3>Current Status:</h3>
-            <p>Video active: {status.isVideoActive ? 'Yes' : 'No'}</p>
-            <p>Step: {status.captureStep}</p>
-            <p>Process completed: {status.isProcessCompleted ? 'Yes' : 'No'}</p>
-            <p>Model preloaded: {status.isModelPreloaded ? 'Yes' : 'No'}</p>
-          </div>
-        )}
-        
-        {capturedData && (
-          <div className="results">
-            <h3>Capture Results:</h3>
-            <p>Total images: {capturedData.metadata.totalImages}</p>
-            <p>Timestamp: {capturedData.timestamp}</p>
-            
-            {capturedData.front.cropped && (
-              <div>
-                <h4>Document Front:</h4>
-                <img 
-                  src={capturedData.front.cropped} 
-                  alt="Document front" 
-                  style={{ maxWidth: '300px', border: '1px solid #ccc', margin: '10px' }}
-                />
-              </div>
-            )}
-            
-            {capturedData.back.cropped && (
-              <div>
-                <h4>Document Back:</h4>
-                <img 
-                  src={capturedData.back.cropped} 
-                  alt="Document back" 
-                  style={{ maxWidth: '300px', border: '1px solid #ccc', margin: '10px' }}
-                />
-              </div>
-            )}
-          </div>
-        )}
-      </header>
-    </div>
-  );
+### Theme Support
+
+The component automatically adapts to system dark/light mode preferences:
+
+```css
+/* Light theme (default) */
+jaak-stamps {
+  --background-color: #ffffff;
+  --text-color: #333333;
+  --border-color: #dddddd;
 }
 
-export default App;
+/* Dark theme */
+@media (prefers-color-scheme: dark) {
+  jaak-stamps {
+    --background-color: #1a1a1a;
+    --text-color: #ffffff;
+    --border-color: #444444;
+  }
+}
 ```
 
-## API Reference
+## Compatibility
 
-### Properties/Attributes
+### Browser Support
 
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `debug` | `boolean` | `false` | Enables debug mode to show debugging information |
-| `alignmentTolerance` | `number` | `15` | Tolerance in pixels to consider a side aligned |
-| `maskSize` | `number` | `80` | Percentage of video that the detection mask will occupy (50-100) |
-| `cropMargin` | `number` | `20` | Margin in pixels added to the document crop (0-100) |
-| `captureDelay` | `number` | `1500` | Time in milliseconds the document must remain in position before automatically capturing (0-10000) |
-| `useDocumentClassification` | `boolean` | `false` | Enables automatic document classification to determine if back capture is required. Only loads the classification model when enabled. |
-| `preferredCamera` | `'auto' \| 'front' \| 'back'` | `'auto'` | Defines which camera to use: `'auto'` (automatic based on device), `'front'` (front camera), `'back'` (back camera) |
-
-### Public Methods
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `startCapture()` | `Promise<void>` | Starts the detection and capture process |
-| `stopCapture()` | `Promise<void>` | Stops the process and releases the camera |
-| `resetCapture()` | `Promise<void>` | Resets the capture process |
-| `preloadModel()` | `Promise<{success: boolean, message?: string, error?: string}>` | Preloads the detection model |
-| `getCapturedImages()` | `Promise<CapturedImages>` | Gets the captured images (only after completion) |
-| `isProcessCompleted()` | `Promise<boolean>` | Checks if the process has been completed |
-| `getStatus()` | `Promise<Status>` | Gets the current detector status |
-| `skipBackCapture()` | `Promise<void>` | Skips back capture (only available in 'back' step) |
-| `getCameraInfo()` | `Promise<CameraInfo>` | Gets detailed information about available cameras |
-| `setPreferredCamera(camera)` | `Promise<{success: boolean, selectedCamera: string, availableCameras: number}>` | Sets the preferred camera ('auto', 'front', 'back') |
-| `setCaptureDelay(delay)` | `Promise<{success: boolean, captureDelay: number}>` | Sets the wait time before automatically capturing (0-10000ms) |
-| `getCaptureDelay()` | `Promise<number>` | Gets the current wait time configured for automatic capture |
-| `setTorchEnabled(enabled)` | `Promise<{success: boolean, enabled: boolean}>` | Enables or disables the camera torch/flash |
-| `focusAtPoint(x, y)` | `Promise<{success: boolean, coordinates: {x: number, y: number}}>` | Focuses the camera at specific coordinates |
+- **Chrome/Edge**: 80+
+- **Firefox**: 75+ 
+- **Safari**: 13+
+- **iOS Safari**: 13+
+- **Chrome Android**: 80+
 
-### Events
+### Framework Compatibility
 
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `captureCompleted` | `CapturedImages` | Emitted when the capture process is completed |
-| `isReady` | `boolean` | Emitted when the component is ready to start detection (models loaded) |
+- **Vanilla JavaScript**: Full support
+- **React**: 16.8+
+- **Angular**: 12+
+- **Vue.js**: 3+
+- **Svelte**: 3+
 
-### Data Types
+### Required Dependencies
 
-```typescript
-interface CapturedImages {
-  front: {
-    fullFrame: string | null;    // Base64 of the complete front image
-    cropped: string | null;      // Base64 of the cropped front document
-  };
-  back: {
-    fullFrame: string | null;    // Base64 of the complete back image
-    cropped: string | null;      // Base64 of the cropped back document
-  };
-  timestamp: string;             // ISO timestamp of capture
-  metadata: {
-    totalImages: number;         // Total number of captured images
-    processCompleted: boolean;   // If the process was completed
-    backCaptureSkipped?: boolean; // If back capture was skipped
-  };
-}
+- **Modern browser** with WebRTC support
+- **Camera access** permission
+- **HTTPS context** (required for camera access)
 
-interface Status {
-  isVideoActive: boolean;        // If the camera is active
-  captureStep: 'front' | 'back' | 'completed'; // Current process step
-  hasImages: boolean;           // If there are captured images
-  isProcessCompleted: boolean;  // If the process is completed
-  isModelPreloaded: boolean;    // If the model is preloaded
-}
+### Optional Dependencies
+
+- **Web Workers** support for enhanced performance
+- **WebAssembly** support for AI model acceleration
+
+## Troubleshooting
+
+### Common Issues
+
+#### Camera Not Working
+
+**Problem**: Camera preview is black or not showing
+
+**Solutions**:
+```javascript
+// Check camera permissions
+const scanner = document.querySelector('jaak-stamps');
+const cameraInfo = await scanner.getCameraInfo();
+console.log('Available cameras:', cameraInfo.availableCameras);
+
+// Try switching cameras
+await scanner.setPreferredCamera('back');
 ```
 
-## Workflow
-
-### Standard Flow (useDocumentClassification = false)
-1. **Initialization**: Component prepares for detection
-2. **Start capture**: Detection model loads automatically
-3. **Front capture**: User positions document and it captures automatically
-4. **Back request**: Always requests to flip document for back capture
-5. **Skip back button**: Available to manually skip back capture
-6. **Completed**: Emits `captureCompleted` event with corresponding images
-
-### Smart Classification Flow (useDocumentClassification = true)
-1. **Initialization**: Component prepares for detection
-2. **Start capture**: Detection and classification models load automatically
-3. **Front capture**: User positions document and it captures automatically
-4. **Automatic classification**: System determines if document requires back capture
-5. **Adaptive flow**: 
-   - **If passport**: Process completes automatically (no back side)
-   - **If other document**: Requests to flip document for back capture
-6. **Completed**: Emits `captureCompleted` event with corresponding images
-
-### Preload Flow (Recommended)
-1. **Model preload**: Call `preloadModel()` to load models in memory
-2. **Optimized start**: When starting capture, uses already loaded models
-3. **Front capture**: Faster detection and classification with preloaded models
-4. **Smart flow**: 
-   - **Document without back**: Process completed immediately
-   - **Document with back**: Requests back capture
-5. **Completed**: Emits `captureCompleted` event with all images
-
-### Document Classification
-
-#### Classification Enabled Mode (`useDocumentClassification = true`)
-When enabled, the system automatically determines if the document requires back capture:
-- **Passports**: Automatically skips back capture
-- **Other documents**: Require capture of both sides (front and back)
-- **Skip back button**: Always available for manual flexibility
-- **Optimized loading**: Classification model downloads only when needed
-
-#### Standard Mode (`useDocumentClassification = false`, default)
-When disabled, behavior is lighter and more direct:
-- **All documents**: Always requests back capture
-- **Skip back button**: Available to manually skip capture
-- **No classification**: Only loads detection model
-- **Lower bandwidth usage**: Downloads only detection model
-
-#### Performance Considerations
-- **Classification disabled**: Faster loading and lower data usage
-- **Classification enabled**: Smarter experience but requires additional model download
-- **On-demand loading**: Classification model loads only when first document is captured
-
-## System Requirements
-
-- **Browsers**: Chrome/Edge 88+, Firefox 85+, Safari 14+
-- **Camera**: Access to rear camera (mobile) or webcam (desktop)
-- **Connection**: Internet connection to load detection models
-
-## Privacy and Performance Considerations
-
-### Privacy
-- Images are processed locally in the browser
-- No data is sent to external servers
-- All processing runs completely on the client side
-- Document classification is performed privately and locally
-- Captured images are only available within your application context
-
-### Resource Optimization
-- **Conditional loading**: Only downloads necessary models based on configuration
-- **Lazy loading**: Models load when actually needed
-- **Browser cache**: Models are stored locally after first download
-
-## Development
-
-### Clone the repository
-```bash
-git clone [repository-url]
-cd jaak-stamps-webcomponent
+#### Slow Performance
+
+**Problem**: Component is slow or laggy
+
+**Solutions**:
+```javascript
+// Preload the AI model
+const scanner = document.querySelector('jaak-stamps');
+await scanner.preloadModel();
+
+// Reduce capture delay for faster response
+await scanner.setCaptureDelay(1000);
+
+// Disable debug mode in production
+scanner.setAttribute('debug', 'false');
 ```
 
-### Install dependencies
-```bash
-npm install
+#### No Images Captured
+
+**Problem**: Capture completes but no images returned
+
+**Solutions**:
+```javascript
+// Check component status
+const status = await scanner.getStatus();
+console.log('Component status:', status);
+
+// Verify capture process completion
+const isCompleted = await scanner.isProcessCompleted();
+if (isCompleted) {
+  const images = await scanner.getCapturedImages();
+  console.log('Images:', images);
+}
 ```
 
-### Local development
-```bash
-npm start
+#### Memory Issues on Mobile
+
+**Problem**: Component crashes on mobile devices
+
+**Solutions**:
+```html
+<!-- Reduce memory usage -->
+<jaak-stamps
+  mask-size="60"
+  crop-margin="15"
+  capture-delay="2000">
+</jaak-stamps>
 ```
 
-### Build for production
-```bash
-npm run build
+### Frequently Asked Questions
+
+**Q: Can I use this component without HTTPS?**
+A: No, camera access requires HTTPS in production. Use `localhost` for development.
+
+**Q: How do I handle multiple document types?**
+A: Enable document classification:
+```html
+<jaak-stamps use-document-classification="true"></jaak-stamps>
 ```
 
-### Run tests
-```bash
-npm test
+**Q: Can I customize the detection area?**
+A: Yes, use the `mask-size` property to adjust the detection frame size.
+
+**Q: How do I get only the cropped images?**
+A: Access the `cropped` property from the captured images:
+```javascript
+const images = await scanner.getCapturedImages();
+const croppedFront = images.front.cropped; // Base64 string
 ```
 
-## Support
+**Q: Is the component accessible?**
+A: Yes, the component includes ARIA labels and keyboard navigation support.
+
+**Q: Can I use this in a Progressive Web App (PWA)?**
+A: Yes, the component is fully compatible with PWAs and works offline after initial load.
 
-To report bugs or request features, please create an issue in the project repository.
+---
 
 ## License
 
-MIT License - see LICENSE file for details.
+MIT © [Jaak AI](https://github.com/jaak-ai)