@srsergio/taptapp-ar 1.0.99 → 1.0.100

package/README.md

@@ -123,32 +123,101 @@ export const MyARScene = () => (
 );
 ```
 
-### 2. The Powerful Way: `startTracking` API
+### 2. High-Performance React Hook: `useAR` 🪝
 
-For vanilla JS or custom integrations, use the new high-level API:
+For more control over the AR state or custom UI overlays:
 
-```typescript
-import { startTracking } from '@srsergio/taptapp-ar';
+```tsx
+import { useAR } from '@srsergio/taptapp-ar/react';
+
+const MyCustomAR = () => {
+  const { 
+    containerRef, 
+    overlayRef, 
+    status, 
+    trackedPoints, 
+    error 
+  } = useAR({
+    targetImageSrc: "target.png",
+    scale: 1.0
+  });
+
+  return (
+    <div ref={containerRef} style={{ width: '100%', height: '100vh' }}>
+      {/* Your custom 3D or 2D overlay */}
+      <video ref={overlayRef} src="content.mp4" />
+      
+      {/* Use trackedPoints for custom visualizations */}
+      {trackedPoints.map((p, i) => (
+        <div key={i} style={{ position: 'absolute', left: p.x, top: p.y }} />
+      ))}
+    </div>
+  );
+};
+```
 
+### 3. Native API: `startTracking`
+
+For vanilla JS or custom integrations:
+
+```typescript
 const tracker = await startTracking({
-    targetSrc: './assets/target.jpg', // No .taar needed!
+    targetSrc: './assets/target.jpg',
     container: document.getElementById('ar-container'),
     overlay: document.getElementById('overlay-element'),
     
-    // Optional callbacks
+    // 📸 Custom Camera Config
+    cameraConfig: {
+        facingMode: 'environment', // Use back camera
+        width: { ideal: 1920 },    // Request Full HD
+        height: { ideal: 1080 }
+    },
+    
     callbacks: {
-        onFound: () => console.log("Target Found! 🎯"),
-        onLost: () => console.log("Target Lost 👋"),
+        onFound: () => console.log("Target Found!"),
         onUpdate: (data) => {
-             console.log("Stability:", data.avgStability);
+             console.log(`Stability: ${data.avgStability}`);
         }
     }
 });
+```
+
+### 4. Custom Overlays (Beyond Video/Images) 🧩
 
-// Stop later
-// tracker.stop();
+The `overlay` isn't limited to images or videos. You can use **any HTML element** (divs, buttons, canvas, etc.). The engine will apply the transformation matrix automatically to align it with the target.
+
+```tsx
+// Using an interactive HTML overlay in React
+const InteractiveAR = () => {
+  const { containerRef, overlayRef, status } = useAR({
+    targetImageSrc: "map.jpg",
+    scale: 1.0
+  });
+
+  return (
+    <div ref={containerRef}>
+      {/* 🚀 This div will be pinned and skewed to the physical target */}
+      <div 
+        ref={overlayRef as any} 
+        style={{ background: 'white', padding: '10px', borderRadius: '8px' }}
+      >
+        <h4>Dynamic UI</h4>
+        <button onClick={() => alert('Clicked!')}>Interacción AR</button>
+      </div>
+    </div>
+  );
+};
 ```
 
+#### `TrackingUpdate` Data Object
+The `onUpdate` callback provides a rich data object:
+- `isTracking`: Boolean status.
+- `avgReliability`: (0-1) Confidence of the match.
+- `avgStability`: (0-1) Movement smoothness.
+- `screenCoords`: Array of `{x, y, id}` of tracked points.
+- `worldMatrix`: 4x4 matrix for WebGL/Three.js integration.
+- `targetDimensions`: `[width, height]` of the source target.
+
 ### 3. Advanced Integration (Three.js / A-Frame)
 
 We still provide wrappers for 3D engines if you need to render complex 3D models instead of DOM overlays.

package/dist/react/types.d.ts

@@ -6,6 +6,7 @@ export interface ARConfig {
     videoWidth: number;
     videoHeight: number;
     scale: number;
+    cameraConfig?: MediaStreamConstraints['video'];
 }
 export interface ARDataItem {
     id: string;

package/dist/react/use-ar.js

@@ -41,6 +41,7 @@ export const useAR = (config) => {
                     targetSrc: config.targetTaarSrc || config.targetImageSrc,
                     overlay: overlayRef.current,
                     scale: config.scale,
+                    cameraConfig: config.cameraConfig,
                     debugMode: false,
                     callbacks: {
                         onUpdate: (data) => {
@@ -104,7 +105,7 @@ export const useAR = (config) => {
             arInstanceRef.current?.stop();
             arInstanceRef.current = null;
         };
-    }, [config.targetTaarSrc, config.targetImageSrc, config.scale]);
+    }, [config.targetTaarSrc, config.targetImageSrc, config.scale, config.cameraConfig]);
     return {
         containerRef,
         overlayRef,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@srsergio/taptapp-ar",
-    "version": "1.0.99",
+    "version": "1.0.100",
     "description": "Ultra-fast Augmented Reality (AR) SDK for Node.js and Browser. Image tracking with 100% pure JavaScript, zero-dependencies, and high-performance compilation.",
     "keywords": [
         "augmented reality",

package/src/react/types.ts

@@ -6,6 +6,7 @@ export interface ARConfig {
   videoWidth: number;
   videoHeight: number;
   scale: number;
+  cameraConfig?: MediaStreamConstraints['video'];
 }
 
 export interface ARDataItem {

package/src/react/use-ar.ts

@@ -65,6 +65,7 @@ export const useAR = (config: ARConfig): UseARReturn => {
                     targetSrc: config.targetTaarSrc || config.targetImageSrc,
                     overlay: overlayRef.current!,
                     scale: config.scale,
+                    cameraConfig: config.cameraConfig,
                     debugMode: false,
                     callbacks: {
                         onUpdate: (data) => {
@@ -129,7 +130,7 @@ export const useAR = (config: ARConfig): UseARReturn => {
             arInstanceRef.current?.stop();
             arInstanceRef.current = null;
         };
-    }, [config.targetTaarSrc, config.targetImageSrc, config.scale]);
+    }, [config.targetTaarSrc, config.targetImageSrc, config.scale, config.cameraConfig]);
 
     return {
         containerRef,