@jaak.ai/stamps 2.0.0-beta.3 → 2.0.0-beta.5

package/README.md

@@ -1,610 +1,761 @@
-# Jaak Stamps - Document Detector Web Component
+# Jaak Stamps Web Component
 
-Un componente web para la detección y captura automática de documentos de identificación usando visión artificial y redes neuronales.
+[![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)
 
-## Características
+[📖 Versión en Español](./README_ES.md)
 
-- 📷 **Detección automática** de documentos de identificación en tiempo real
-- 🎯 **Guía visual** para posicionamiento óptimo del documento
-- 🤖 **Clasificación inteligente** de documentos para determinar si requieren reverso
-- 📋 **Captura adaptativa** - automáticamente detecta si el documento tiene reverso
-- 🖼 **Doble salida** para cada lado: imagen completa y recorte del documento
-- ✂️ **Recorte configurable** con margen personalizable alrededor del documento
-- 🔧 **API programática** para control total del proceso
-- 📱 **Responsive** y compatible con dispositivos móviles
-- ⚡ **Optimización automática** para mejor rendimiento
+## Description
 
-## Instalación
+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/Yarn
 
-### NPM
 ```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 };
+}>
+```
+
+#### Capture Control
+
+```typescript
+// Start the capture process
+startCapture(): Promise<void>
+
+// Stop the capture process
+stopCapture(): Promise<void>
+
+// Reset capture state
+resetCapture(): Promise<void>
+
+// 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;
+}>
 ```
 
-## Uso Básico
+### Events
+
+| Event | Detail Type | Description |
+|-------|-------------|-------------|
+| `isReady` | `boolean` | Fired when component is fully initialized and ready |
+| `captureCompleted` | `object` | Fired when document capture process is completed |
 
-### HTML Vanilla
+### 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="90" crop-margin="10" 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()">Iniciar Captura</button>
-    <button onclick="stopCapture()">Detener</button>
-    <button onclick="resetCapture()">Reiniciar</button>
-
-    <script>
-        const detector = document.getElementById('detector');
-        
-        // Escuchar evento de captura completada
-        detector.addEventListener('captureCompleted', (event) => {
-            console.log('Captura completada:', event.detail);
-            // event.detail contiene las imágenes capturadas
-        });
-        
-        // Escuchar evento de componente listo
-        detector.addEventListener('isReady', (event) => {
-            console.log('Componente listo:', event.detail);
-            // event.detail indica si el componente está listo (true/false)
-        });
-        
-        function startCapture() {
-            detector.startCapture();
-        }
-        
-        function stopCapture() {
-            detector.stopCapture();
-        }
-        
-        function resetCapture() {
-            detector.resetCapture();
-        }
-        
-        // Precargar el modelo (opcional - mejora el rendimiento)
-        async function preloadModel() {
-            try {
-                const result = await detector.preloadModel();
-                console.log('Modelo precargado:', result);
-            } catch (error) {
-                console.error('Error al precargar:', error);
-            }
-        }
-        
-        // Obtener imágenes después de la captura
-        async function getImages() {
-            try {
-                const images = await detector.getCapturedImages();
-                console.log('Imágenes capturadas:', 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. Instalar el componente
-```bash
-npm install @jaak.ai/stamps
-```
+```tsx
+import React, { useEffect, useRef, useState } from 'react';
+import { defineCustomElements } from '@jaak.ai/stamps/loader';
 
-#### 2. Configurar el módulo (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();
 
-// Importar el componente web
-import '@jaak.ai/stamps/dist/jaak-stamps-webcomponent/jaak-stamps-webcomponent.esm.js';
+// Extend HTMLElement for TypeScript
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      'jaak-stamps': any;
+    }
+  }
+}
 
-@NgModule({
-  declarations: [AppComponent],
-  imports: [BrowserModule],
-  providers: [],
-  bootstrap: [AppComponent],
-  schemas: [CUSTOM_ELEMENTS_SCHEMA] // Permitir elementos personalizados
-})
-export class AppModule { }
+interface CapturedImages {
+  front: { fullFrame: string | null; cropped: string | null };
+  back: { fullFrame: string | null; cropped: string | null };
+  metadata: {
+    totalImages: number;
+    processCompleted: boolean;
+    backCaptureSkipped: boolean;
+  };
+}
+
+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. Usar en el componente
+### 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>Detector de Documentos</h1>
+    <div class="scanner-container">
+      <h2>Document Scanner</h2>
       
-      <jaak-stamps 
-        #detector
-        [debug]="false"
-        [maskSize]="90"
-        [cropMargin]="10"
-        [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()">Precargar Modelo</button>
-        <button (click)="startCapture()">Iniciar Captura</button>
-        <button (click)="stopCapture()">Detener</button>
-        <button (click)="resetCapture()">Reiniciar</button>
-        <button (click)="getImages()" [disabled]="!isCompleted">Obtener Imágenes</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>Imágenes Capturadas:</h3>
-        <p>Total de imágenes: {{ capturedData.metadata.totalImages }}</p>
-        <img *ngIf="capturedData.front.cropped" [src]="capturedData.front.cropped" alt="Frente">
-        <img *ngIf="capturedData.back.cropped" [src]="capturedData.back.cropped" alt="Reverso">
+      <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() {
-    // El elemento ya está disponible después de la vista
-  }
-  
-  async preloadModel() {
-    try {
-      const result = await this.detectorRef.nativeElement.preloadModel();
-      console.log('Modelo precargado:', result);
-    } catch (error) {
-      console.error('Error al precargar modelo:', error);
+    .scanner-container {
+      max-width: 600px;
+      margin: 0 auto;
+      padding: 20px;
     }
-  }
-
-  async startCapture() {
-    try {
-      await this.detectorRef.nativeElement.startCapture();
-    } catch (error) {
-      console.error('Error al iniciar captura:', 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('Imágenes obtenidas:', images);
-    } catch (error) {
-      console.error('Error al obtener imágenes:', error);
+  async startScan() {
+    if (this.scannerRef?.nativeElement) {
+      await this.scannerRef.nativeElement.startCapture();
     }
   }
   
-  onCaptureCompleted(event: any) {
-    console.log('Captura completada en Angular:', event.detail);
-    this.capturedData = event.detail;
-    this.isCompleted = true;
-  }
-  
-  onComponentReady(event: any) {
-    console.log('Componente listo en Angular:', event.detail);
-    // El componente está listo para iniciar detección
+  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. Instalar el componente
-```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. Crear componente wrapper (opcional pero recomendado)
-```jsx
-// JaakStampsWrapper.jsx
-import React, { useRef, useEffect, useImperativeHandle, forwardRef } from 'react';
+## Style Guide
+
+### CSS Custom Properties
 
-// Importar el 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 = 90, cropMargin = 0, 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}
-    />
-  );
-});
-
-export default JaakStampsWrapper;
+  /* Status indicator colors */
+  --status-success-color: #28a745;
+  --status-warning-color: #ffc107;
+  --status-error-color: #dc3545;
+}
 ```
 
-#### 3. Usar en tu aplicación React
-```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('Captura completada:', data);
-    setCapturedData(data);
-    setIsCompleted(true);
-  };
-  
-  const handleIsReady = (isReady) => {
-    console.log('Componente listo:', isReady);
-    // El componente está listo para iniciar detección
-  };
-  
-  const preloadModel = async () => {
-    try {
-      const result = await detectorRef.current?.preloadModel();
-      console.log('Modelo precargado:', result);
-    } catch (error) {
-      console.error('Error al precargar modelo:', error);
-    }
-  };
-  
-  const startCapture = async () => {
-    try {
-      await detectorRef.current?.startCapture();
-    } catch (error) {
-      console.error('Error al iniciar captura:', 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('Imágenes obtenidas:', images);
-    } catch (error) {
-      console.error('Error al obtener imágenes:', error);
-    }
-  };
-  
-  const checkStatus = async () => {
-    const currentStatus = await detectorRef.current?.getStatus();
-    setStatus(currentStatus);
-  };
-  
-  return (
-    <div className="App">
-      <header className="App-header">
-        <h1>Detector de Documentos - React</h1>
-        
-        <JaakStampsWrapper 
-          ref={detectorRef}
-          debug={false}
-          maskSize={90}
-          cropMargin={10}
-          useDocumentClassification={false}
-          onCaptureCompleted={handleCaptureCompleted}
-          onIsReady={handleIsReady}
-        />
-        
-        <div className="controls">
-          <button onClick={preloadModel}>Precargar Modelo</button>
-          <button onClick={startCapture}>Iniciar Captura</button>
-          <button onClick={stopCapture}>Detener</button>
-          <button onClick={resetCapture}>Reiniciar</button>
-          <button onClick={getImages} disabled={!isCompleted}>
-            Obtener Imágenes
-          </button>
-          <button onClick={checkStatus}>Verificar Estado</button>
-        </div>
-        
-        {status && (
-          <div className="status">
-            <h3>Estado Actual:</h3>
-            <p>Video activo: {status.isVideoActive ? 'Sí' : 'No'}</p>
-            <p>Paso: {status.captureStep}</p>
-            <p>Mensaje: {status.statusMessage}</p>
-            <p>Proceso completado: {status.isProcessCompleted ? 'Sí' : 'No'}</p>
-            <p>Modelo precargado: {status.isModelPreloaded ? 'Sí' : 'No'}</p>
-          </div>
-        )}
-        
-        {capturedData && (
-          <div className="results">
-            <h3>Resultados de la Captura:</h3>
-            <p>Total de imágenes: {capturedData.metadata.totalImages}</p>
-            <p>Timestamp: {capturedData.timestamp}</p>
-            
-            {capturedData.front.cropped && (
-              <div>
-                <h4>Frente del Documento:</h4>
-                <img 
-                  src={capturedData.front.cropped} 
-                  alt="Frente del documento" 
-                  style={{ maxWidth: '300px', border: '1px solid #ccc', margin: '10px' }}
-                />
-              </div>
-            )}
-            
-            {capturedData.back.cropped && (
-              <div>
-                <h4>Reverso del Documento:</h4>
-                <img 
-                  src={capturedData.back.cropped} 
-                  alt="Reverso del documento" 
-                  style={{ maxWidth: '300px', border: '1px solid #ccc', margin: '10px' }}
-                />
-              </div>
-            )}
-          </div>
-        )}
-      </header>
-    </div>
-  );
+### 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;
 }
 
-export default App;
+/* Responsive design */
+@media (max-width: 768px) {
+  jaak-stamps {
+    --camera-height: 300px;
+  }
+}
 ```
 
-## API Reference
+### Theme Support
 
-### Props/Atributos
-
-| Propiedad | Tipo | Predeterminado | Descripción |
-|-----------|------|---------------|-------------|
-| `debug` | `boolean` | `false` | Activa el modo debug para mostrar información de depuración |
-| `alignmentTolerance` | `number` | `10` | Tolerancia en píxeles para considerar un lado alineado |
-| `maskSize` | `number` | `90` | Porcentaje del video que ocupará la máscara de detección (50-100) |
-| `cropMargin` | `number` | `0` | Margen en píxeles agregado al recorte del documento (0-100) |
-| `useDocumentClassification` | `boolean` | `false` | Habilita la clasificación automática de documentos para determinar si solicitar reverso. Solo carga el modelo de clasificación cuando está habilitada. |
-| `preferredCamera` | `'auto' \| 'front' \| 'back'` | `'auto'` | Define qué cámara usar: `'auto'` (automático según dispositivo), `'front'` (cámara frontal), `'back'` (cámara trasera) |
-
-### Métodos Públicos
-
-| Método | Retorna | Descripción |
-|--------|---------|-------------|
-| `startCapture()` | `Promise<void>` | Inicia el proceso de detección y captura |
-| `stopCapture()` | `Promise<void>` | Detiene el proceso y libera la cámara |
-| `resetCapture()` | `Promise<void>` | Reinicia el proceso de captura |
-| `preloadModel()` | `Promise<{success: boolean, message?: string, error?: string}>` | Precarga el modelo de detección |
-| `getCapturedImages()` | `Promise<CapturedImages>` | Obtiene las imágenes capturadas (solo después de completar) |
-| `isProcessCompleted()` | `Promise<boolean>` | Verifica si el proceso ha sido completado |
-| `getStatus()` | `Promise<Status>` | Obtiene el estado actual del detector |
-| `skipBackCapture()` | `Promise<void>` | Omite la captura del reverso (solo disponible en paso 'back') |
-| `getCameraInfo()` | `Promise<CameraInfo>` | Obtiene información detallada sobre las cámaras disponibles |
-| `setPreferredCamera(camera)` | `Promise<{success: boolean, selectedCamera: string, availableCameras: number}>` | Configura la cámara preferida ('auto', 'front', 'back') |
-
-### Eventos
-
-| Evento | Payload | Descripción |
-|--------|---------|-------------|
-| `captureCompleted` | `CapturedImages` | Se emite cuando se completa el proceso de captura |
-| `isReady` | `boolean` | Se emite cuando el componente está listo para comenzar la detección (modelos cargados) |
-
-### Tipos de Datos
+The component automatically adapts to system dark/light mode preferences:
 
-```typescript
-interface CapturedImages {
-  front: {
-    fullFrame: string | null;    // Base64 de la imagen completa del frente
-    cropped: string | null;      // Base64 del documento recortado del frente
-  };
-  back: {
-    fullFrame: string | null;    // Base64 de la imagen completa del reverso
-    cropped: string | null;      // Base64 del documento recortado del reverso
-  };
-  timestamp: string;             // ISO timestamp de la captura
-  metadata: {
-    totalImages: number;         // Número total de imágenes capturadas
-    processCompleted: boolean;   // Si el proceso fue completado
-    backCaptureSkipped?: boolean; // Si se omitió la captura del reverso
-  };
+```css
+/* Light theme (default) */
+jaak-stamps {
+  --background-color: #ffffff;
+  --text-color: #333333;
+  --border-color: #dddddd;
 }
 
-interface Status {
-  isVideoActive: boolean;        // Si la cámara está activa
-  captureStep: 'front' | 'back' | 'completed'; // Paso actual del proceso
-  statusMessage: string;         // Mensaje de estado actual
-  hasImages: boolean;           // Si hay imágenes capturadas
-  isProcessCompleted: boolean;  // Si el proceso está completado
-  isModelPreloaded: boolean;    // Si el modelo está precargado
+/* Dark theme */
+@media (prefers-color-scheme: dark) {
+  jaak-stamps {
+    --background-color: #1a1a1a;
+    --text-color: #ffffff;
+    --border-color: #444444;
+  }
 }
 ```
 
-## Flujo de Trabajo
-
-### Flujo Estándar (useDocumentClassification = false)
-1. **Inicialización**: El componente se prepara para la detección
-2. **Inicio de captura**: Se carga automáticamente el modelo de detección
-3. **Captura del frente**: El usuario posiciona el documento y se captura automáticamente
-4. **Solicitud de reverso**: Siempre se solicita voltear el documento para capturar el reverso
-5. **Botón "Saltar reverso"**: Disponible para omitir manualmente la captura del reverso
-6. **Completado**: Se emite el evento `captureCompleted` con las imágenes correspondientes
-
-### Flujo con Clasificación Inteligente (useDocumentClassification = true)
-1. **Inicialización**: El componente se prepara para la detección
-2. **Inicio de captura**: Se cargan automáticamente los modelos de detección y clasificación
-3. **Captura del frente**: El usuario posiciona el documento y se captura automáticamente
-4. **Clasificación automática**: El sistema determina si el documento requiere captura de reverso
-5. **Flujo adaptativo**: 
-   - **Si es pasaporte**: Se completa automáticamente el proceso (sin reverso)
-   - **Si es otro documento**: Se solicita voltear el documento para capturar el reverso
-6. **Completado**: Se emite el evento `captureCompleted` con las imágenes correspondientes
-
-### Flujo con Precarga (Recomendado)
-1. **Precarga de modelos**: Se llama a `preloadModel()` para cargar ambos modelos en memoria
-2. **Inicio optimizado**: Al iniciar la captura, se usan los modelos ya cargados
-3. **Captura del frente**: Detección y clasificación más rápidas con modelos precargados
-4. **Flujo inteligente**: 
-   - **Documento sin reverso**: Proceso completado inmediatamente
-   - **Documento con reverso**: Se solicita captura del reverso
-5. **Completado**: Se emite el evento `captureCompleted` con todas las imágenes
-
-### Clasificación de Documentos
-
-#### Modo con Clasificación Habilitada (`useDocumentClassification = true`)
-Cuando la propiedad está habilitada, el sistema utiliza un modelo de inteligencia artificial especializado para determinar automáticamente si el documento requiere captura de reverso:
-- **Pasaportes**: Se omite automáticamente la captura del reverso
-- **Otros documentos**: Requieren captura de ambos lados (frente y reverso)
-- **Botón "Saltar reverso"**: Siempre disponible para permitir flexibilidad manual
-- **Carga optimizada**: El modelo de clasificación se descarga solo cuando es necesario
-
-#### Modo Estándar (`useDocumentClassification = false`, por defecto)
-Cuando está deshabilitada, el comportamiento es más liviano y directo:
-- **Todos los documentos**: Siempre se solicita captura del reverso
-- **Botón "Saltar reverso"**: Disponible para omitir manualmente la captura
-- **Sin clasificación**: NO se carga el modelo de clasificación, solo el de detección
-- **Menor uso de ancho de banda**: Solo descarga el modelo de detección (~5MB menos)
-
-#### Consideraciones de Rendimiento
-- **Con clasificación deshabilitada**: Carga más rápida y menor uso de datos
-- **Con clasificación habilitada**: Experiencia más inteligente pero requiere descargar modelo adicional
-- **Carga bajo demanda**: El modelo de clasificación se carga solo cuando se captura el primer documento
-
-## Requisitos del Sistema
-
-- **Navegadores**: Chrome/Edge 88+, Firefox 85+, Safari 14+
-- **Cámara**: Acceso a cámara trasera (móvil) o webcam (escritorio)
-- **Conexión**: Conexión a internet para cargar los modelos de IA
-
-## Consideraciones de Privacidad y Rendimiento
-
-### Privacidad
-- Las imágenes se procesan localmente en el navegador
-- No se envían datos a servidores externos
-- Los modelos de IA (detección y clasificación) se ejecutan completamente en el cliente
-- La clasificación de documentos se realiza de forma privada y local
-- Las imágenes capturadas solo están disponibles en el contexto de tu aplicación
-
-### Optimización de Recursos
-- **Carga condicional**: Solo descarga modelos necesarios según configuración
-- **Modelo de detección**: ~15MB (siempre requerido)
-- **Modelo de clasificación**: ~5MB (solo si `useDocumentClassification = true`)
-- **Lazy loading**: Los modelos se cargan cuando realmente se necesitan
-- **Cache del navegador**: Los modelos se almacenan localmente después de la primera descarga
-
-## Desarrollo
-
-### Clonar el repositorio
-```bash
-git clone [repository-url]
-cd jaak-stamps-webcomponent
+## Compatibility
+
+### Browser Support
+
+- **Chrome/Edge**: 80+
+- **Firefox**: 75+ 
+- **Safari**: 13+
+- **iOS Safari**: 13+
+- **Chrome Android**: 80+
+
+### Framework Compatibility
+
+- **Vanilla JavaScript**: Full support
+- **React**: 16.8+
+- **Angular**: 12+
+- **Vue.js**: 3+
+- **Svelte**: 3+
+
+### Required Dependencies
+
+- **Modern browser** with WebRTC support
+- **Camera access** permission
+- **HTTPS context** (required for camera access)
+
+### 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');
 ```
 
-### Instalar dependencias
-```bash
-npm install
+#### 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');
 ```
 
-### Desarrollo local
-```bash
-npm start
+#### 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);
+}
 ```
 
-### Construir para producción
-```bash
-npm run build
+#### 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>
 ```
 
-### Ejecutar tests
-```bash
-npm test
+### 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>
 ```
 
-## Soporte
+**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
+```
+
+**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.
 
-Para reportar bugs o solicitar características, por favor crea un issue en el repositorio del proyecto.
+---
 
-## Licencia
+## License
 
-MIT License - ver archivo LICENSE para detalles.
+MIT © [Jaak AI](https://github.com/jaak-ai)