@srsergio/taptapp-ar 1.0.98 → 1.0.100

package/LICENSE

@@ -1,4 +1,4 @@
-MIT License
+Fair Source License v0.9
 
 Copyright (c) 2026 Sergio Lázaro
 
@@ -9,8 +9,16 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+1. The above copyright notice and this permission notice shall be included in
+   all copies or substantial portions of the Software.
+
+2. A "Large Entity" (defined below) must obtain a separate commercial license
+   from the copyright holder before using the Software in any commercial
+   context.
+
+3. "Large Entity" means any organization or individual that:
+   a. Has 100 or more employees; or
+   b. Has $10,000,000 USD or more in annual revenue.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
@@ -19,3 +27,4 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@srsergio/taptapp-ar.svg?style=flat-square)](https://www.npmjs.com/package/@srsergio/taptapp-ar)
 [![npm downloads](https://img.shields.io/npm/dm/@srsergio/taptapp-ar.svg?style=flat-square)](https://www.npmjs.com/package/@srsergio/taptapp-ar)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![License: Fair Source-0.9](https://img.shields.io/badge/License-Fair_Source--0.9-blue.svg?style=flat-square)](./LICENSE)
 [![Bundle Size](https://img.shields.io/bundlephobia/minzip/@srsergio/taptapp-ar?style=flat-square)](https://bundlephobia.com/package/@srsergio/taptapp-ar)
 
 🚀 **TapTapp AR** is a high-performance Augmented Reality (AR) toolkit for **Node.js** and **Browser** environments. It provides an ultra-fast offline compiler and a lightweight runtime for image tracking.
@@ -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.
@@ -178,7 +247,17 @@ TapTapp AR uses a proprietary **Nanite-style Vision Codec** that is significantl
 
 ## 📄 License & Credits
 
+This project is licensed under the **Fair Source License v0.9**.
+
+### What does this mean?
+- **Small Entities & Individuals**: You can use, modify, and distribute this software for **FREE** (including commercial use).
+- **Large Entities**: If your organization has **100+ employees** OR **$10,000,000+ USD in annual revenue**, you must obtain a separate commercial license from the copyright holder before using it in a commercial context.
+
+This model allows us to keep the project open and free for the community while ensuring sustainability from large-scale corporate usage.
+
+---
 MIT © [srsergiolazaro](https://github.com/srsergiolazaro)
 
-Based on the core research of MindAR, but completely re-written for high-performance binary processing and JS-only execution.
+Based on core research from the community, but completely re-written for high-performance binary processing and JS-only execution.
+
 

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.98",
+    "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",
@@ -23,7 +23,7 @@
         "natural-feature-tracking"
     ],
     "author": "Sergio Lázaro <slazaro.dev@gmail.com>",
-    "license": "MIT",
+    "license": "Fair Source-0.9",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/srsergiolazaro/taptapp-ar.git"

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,