@srsergio/taptapp-ar 1.0.11 → 1.0.13

package/README.md

@@ -95,27 +95,144 @@ renderer.setAnimationLoop(() => {
 });
 ```
 
-### 3. Raw Controller (Custom Logic)
-Use the `Controller` directly for maximum control:
+### 3. Raw Controller (Advanced & Custom Engines)
+The `Controller` is the core engine of TapTapp AR. You can use it to build your own AR components or integrate tracking into custom 3D engines.
+
+#### ⚙️ Controller Configuration
+| Property | Default | Description |
+| :--- | :--- | :--- |
+| `inputWidth` | **Required** | The width of the video or image source. |
+| `inputHeight` | **Required** | The height of the video or image source. |
+| `maxTrack` | `1` | Max number of images to track simultaneously. |
+| `warmupTolerance` | `5` | Frames of consistent detection needed to "lock" a target. |
+| `missTolerance` | `5` | Frames of missed detection before considering the target "lost". |
+| `filterMinCF` | `0.001` | Min cutoff frequency for the OneEuroFilter (reduces jitter). |
+| `filterBeta` | `1000` | Filter beta parameter (higher = more responsive, lower = smoother). |
+| `onUpdate` | `null` | Callback for tracking events (Found, Lost, ProcessDone). |
+| `debugMode` | `false` | If true, returns extra debug data (cropped images, feature points). |
+| `worker` | `null` | Pass a custom worker instance if using a specialized environment. |
+
+#### 🚀 Example: Tracking a Video Stream
+Ideal for real-time AR apps in the browser:
 
 ```javascript
 import { Controller } from '@srsergio/taptapp-ar';
 
 const controller = new Controller({
-  inputWidth: 640,
-  inputHeight: 480,
+  inputWidth: video.videoWidth,
+  inputHeight: video.videoHeight,
   onUpdate: (data) => {
     if (data.type === 'updateMatrix') {
-      // worldMatrix found! Apply to your 3D engine
       const { targetIndex, worldMatrix } = data;
+      if (worldMatrix) {
+        console.log(`Target ${targetIndex} detected! Matrix:`, worldMatrix);
+        // Apply worldMatrix (Float32Array[16]) to your 3D object
+      } else {
+        console.log(`Target ${targetIndex} lost.`);
+      }
     }
   }
 });
 
+// Single target
 await controller.addImageTargets('./targets.mind');
-controller.processVideo(videoElement);
+
+// OR multiple targets from different .mind files
+await controller.addImageTargets(['./target1.mind', './target2.mind', './target3.mind']);
+controller.processVideo(videoElement); // Starts the internal RAF loop
+```
+
+#### 📸 Example: One-shot Image Matching
+Use this for "Snap and Detect" features without a continuous video loop:
+
+```javascript
+const controller = new Controller({ inputWidth: 1024, inputHeight: 1024 });
+await controller.addImageTargets('./targets.mind');
+
+// 1. Detect features in a static image
+const { featurePoints } = await controller.detect(canvasElement);
+
+// 2. Attempt to match against a specific target index
+const { targetIndex, modelViewTransform } = await controller.match(featurePoints, 0);
+
+if (targetIndex !== -1) {
+  // Found a match! Use modelViewTransform for initial pose estimation
+}
+```
+
+### 4. Vanilla JS (No Framework) 🍦
+The **simplest way** to use AR—no Three.js, no A-Frame. Just overlay an image on the tracked target.
+
+```javascript
+import { SimpleAR } from '@srsergio/taptapp-ar';
+
+const ar = new SimpleAR({
+  container: document.getElementById('ar-container'),
+  targetSrc: './my-target.mind',  // Single URL or array: ['./a.mind', './b.mind']
+  overlay: document.getElementById('my-overlay'),
+  onFound: ({ targetIndex }) => console.log(`Target ${targetIndex} detected! 🎯`),
+  onLost: ({ targetIndex }) => console.log(`Target ${targetIndex} lost 👋`)
+});
+
+await ar.start();
+
+// When done:
+ar.stop();
 ```
 
+#### 📁 Minimal HTML
+```html
+<div id="ar-container" style="width: 100vw; height: 100vh;">
+  <img id="my-overlay" src="./overlay.png" 
+       style="opacity: 0; z-index: 1; width: 200px; transition: opacity 0.3s;" />
+</div>
+
+<script type="module">
+  import { SimpleAR } from '@srsergio/taptapp-ar';
+  
+  const ar = new SimpleAR({
+    container: document.getElementById('ar-container'),
+    targetSrc: './targets.mind',
+    overlay: document.getElementById('my-overlay'),
+  });
+  
+  ar.start();
+</script>
+```
+
+#### ⚙️ SimpleAR Options
+| Option | Required | Description |
+| :--- | :--- | :--- |
+| `container` | ✅ | DOM element where video + overlay render |
+| `targetSrc` | ✅ | URL to your `.mind` file |
+| `overlay` | ✅ | DOM element to position on the target |
+| `onFound` | ❌ | Callback when target is detected |
+| `onLost` | ❌ | Callback when target is lost |
+| `onUpdate` | ❌ | Called each frame with `{ targetIndex, worldMatrix }` |
+| `cameraConfig` | ❌ | Camera constraints (default: `{ facingMode: 'environment', width: 1280, height: 720 }`) |
+
+---
+
+#### 🛠️ Life-cycle Management
+Properly management is crucial to avoid memory leaks:
+
+```javascript
+// Stop the video loop
+controller.stopProcessVideo();
+
+// Clean up workers and internal buffers
+controller.dispose();
+```
+
+---
+
+## 🏗️ Protocol V3 (Columnar Binary Format)
+TapTapp AR uses a proprietary columnar binary format that is significantly more efficient than standard JSON-based formats.
+
+- **Zero-Copy Restoration**: Binary buffers are mapped directly to TypedArrays.
+- **Cache Locality**: Performance is optimized for modern CPUs by keeping coordinates and descriptors adjacent in memory.
+- **Alignment Safe**: Automatically handles `ArrayBuffer` alignment for predictable behavior across all browsers.
+
 ---
 
 ## 📄 License & Credits

package/dist/compiler/controller.d.ts

@@ -31,13 +31,35 @@ export class Controller {
     projectionMatrix: number[];
     _setupWorkerListener(): void;
     _ensureWorker(): void;
-    addImageTargets(fileURL: any): Promise<any>;
-    addImageTargetsFromBuffer(buffer: any): {
+    /**
+     * Load image targets from one or multiple .mind files
+     * @param {string|string[]} fileURLs - Single URL or array of URLs to .mind files
+     * @returns {Promise<{dimensions, matchingDataList, trackingDataList}>}
+     */
+    addImageTargets(fileURLs: string | string[]): Promise<{
+        dimensions: any;
+        matchingDataList: any;
+        trackingDataList: any;
+    }>;
+    /**
+     * Load image targets from multiple ArrayBuffers
+     * @param {ArrayBuffer[]} buffers - Array of .mind file buffers
+     */
+    addImageTargetsFromBuffers(buffers: ArrayBuffer[]): {
         dimensions: any[][];
         matchingDataList: any[];
         trackingDataList: any[];
     };
     tracker: Tracker | undefined;
+    /**
+     * Load image targets from a single ArrayBuffer (backward compatible)
+     * @param {ArrayBuffer} buffer - Single .mind file buffer
+     */
+    addImageTargetsFromBuffer(buffer: ArrayBuffer): {
+        dimensions: any[][];
+        matchingDataList: any[];
+        trackingDataList: any[];
+    };
     dispose(): void;
     dummyRun(input: any): void;
     getProjectionMatrix(): number[];

package/dist/compiler/controller.js

@@ -75,27 +75,39 @@ class Controller {
             this._setupWorkerListener();
         }
     }
-    addImageTargets(fileURL) {
-        return new Promise(async (resolve) => {
-            const content = await fetch(fileURL);
-            const buffer = await content.arrayBuffer();
-            const result = this.addImageTargetsFromBuffer(buffer);
-            resolve(result);
-        });
+    /**
+     * Load image targets from one or multiple .mind files
+     * @param {string|string[]} fileURLs - Single URL or array of URLs to .mind files
+     * @returns {Promise<{dimensions, matchingDataList, trackingDataList}>}
+     */
+    async addImageTargets(fileURLs) {
+        const urls = Array.isArray(fileURLs) ? fileURLs : [fileURLs];
+        // Fetch all .mind files in parallel
+        const buffers = await Promise.all(urls.map(async (url) => {
+            const response = await fetch(url);
+            return response.arrayBuffer();
+        }));
+        // Combine all buffers into a single target list
+        return this.addImageTargetsFromBuffers(buffers);
     }
-    addImageTargetsFromBuffer(buffer) {
-        const compiler = new Compiler();
-        const dataList = compiler.importData(buffer);
-        const trackingDataList = [];
-        const matchingDataList = [];
-        const dimensions = [];
-        for (let i = 0; i < dataList.length; i++) {
-            const item = dataList[i];
-            matchingDataList.push(item.matchingData);
-            trackingDataList.push(item.trackingData);
-            dimensions.push([item.targetImage.width, item.targetImage.height]);
+    /**
+     * Load image targets from multiple ArrayBuffers
+     * @param {ArrayBuffer[]} buffers - Array of .mind file buffers
+     */
+    addImageTargetsFromBuffers(buffers) {
+        const allTrackingData = [];
+        const allMatchingData = [];
+        const allDimensions = [];
+        for (const buffer of buffers) {
+            const compiler = new Compiler();
+            const dataList = compiler.importData(buffer);
+            for (const item of dataList) {
+                allMatchingData.push(item.matchingData);
+                allTrackingData.push(item.trackingData);
+                allDimensions.push([item.targetImage.width, item.targetImage.height]);
+            }
         }
-        this.tracker = new Tracker(dimensions, trackingDataList, this.projectionTransform, this.inputWidth, this.inputHeight, this.debugMode);
+        this.tracker = new Tracker(allDimensions, allTrackingData, this.projectionTransform, this.inputWidth, this.inputHeight, this.debugMode);
         this._ensureWorker();
         if (this.worker) {
             this.worker.postMessage({
@@ -104,11 +116,18 @@ class Controller {
                 inputHeight: this.inputHeight,
                 projectionTransform: this.projectionTransform,
                 debugMode: this.debugMode,
-                matchingDataList,
+                matchingDataList: allMatchingData,
             });
         }
-        this.markerDimensions = dimensions;
-        return { dimensions, matchingDataList, trackingDataList };
+        this.markerDimensions = allDimensions;
+        return { dimensions: allDimensions, matchingDataList: allMatchingData, trackingDataList: allTrackingData };
+    }
+    /**
+     * Load image targets from a single ArrayBuffer (backward compatible)
+     * @param {ArrayBuffer} buffer - Single .mind file buffer
+     */
+    addImageTargetsFromBuffer(buffer) {
+        return this.addImageTargetsFromBuffers([buffer]);
     }
     dispose() {
         this.stopProcessVideo();

package/dist/compiler/simple-ar.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 🍦 SimpleAR - Dead-simple vanilla AR for image overlays
+ *
+ * No Three.js. No A-Frame. Just HTML, CSS, and JavaScript.
+ *
+ * @example
+ * const ar = new SimpleAR({
+ *   container: document.getElementById('ar-container'),
+ *   targetSrc: './my-target.mind',
+ *   overlay: document.getElementById('my-overlay'),
+ *   onFound: () => console.log('Target found!'),
+ *   onLost: () => console.log('Target lost!')
+ * });
+ *
+ * await ar.start();
+ */
+export class SimpleAR {
+    constructor({ container, targetSrc, overlay, onFound, onLost, onUpdate, cameraConfig, }: {
+        container: any;
+        targetSrc: any;
+        overlay: any;
+        onFound?: null | undefined;
+        onLost?: null | undefined;
+        onUpdate?: null | undefined;
+        cameraConfig?: {
+            facingMode: string;
+            width: number;
+            height: number;
+        } | undefined;
+    });
+    container: any;
+    targetSrc: any;
+    overlay: any;
+    onFound: any;
+    onLost: any;
+    onUpdateCallback: any;
+    cameraConfig: {
+        facingMode: string;
+        width: number;
+        height: number;
+    };
+    video: HTMLVideoElement | null;
+    controller: Controller | null;
+    isTracking: boolean;
+    lastMatrix: any;
+    /**
+   * Initialize and start AR tracking
+   */
+    start(): Promise<this>;
+    /**
+     * Stop AR tracking and release resources
+     */
+    stop(): void;
+    _createVideo(): void;
+    _startCamera(): Promise<void>;
+    _initController(): void;
+    _handleUpdate(data: any): void;
+    _positionOverlay(worldMatrix: any): void;
+}
+import { Controller } from "./controller.js";

package/dist/compiler/simple-ar.js

@@ -0,0 +1,173 @@
+import { Controller } from "./controller.js";
+/**
+ * 🍦 SimpleAR - Dead-simple vanilla AR for image overlays
+ *
+ * No Three.js. No A-Frame. Just HTML, CSS, and JavaScript.
+ *
+ * @example
+ * const ar = new SimpleAR({
+ *   container: document.getElementById('ar-container'),
+ *   targetSrc: './my-target.mind',
+ *   overlay: document.getElementById('my-overlay'),
+ *   onFound: () => console.log('Target found!'),
+ *   onLost: () => console.log('Target lost!')
+ * });
+ *
+ * await ar.start();
+ */
+class SimpleAR {
+    constructor({ container, targetSrc, overlay, onFound = null, onLost = null, onUpdate = null, cameraConfig = { facingMode: 'environment', width: 1280, height: 720 }, }) {
+        this.container = container;
+        this.targetSrc = targetSrc;
+        this.overlay = overlay;
+        this.onFound = onFound;
+        this.onLost = onLost;
+        this.onUpdateCallback = onUpdate;
+        this.cameraConfig = cameraConfig;
+        this.video = null;
+        this.controller = null;
+        this.isTracking = false;
+        this.lastMatrix = null;
+    }
+    /**
+   * Initialize and start AR tracking
+   */
+    async start() {
+        // 1. Create video element
+        this._createVideo();
+        // 2. Start camera
+        await this._startCamera();
+        // 3. Initialize controller
+        this._initController();
+        // 4. Load targets (supports single URL or array of URLs)
+        const targets = Array.isArray(this.targetSrc) ? this.targetSrc : [this.targetSrc];
+        await this.controller.addImageTargets(targets);
+        this.controller.processVideo(this.video);
+        return this;
+    }
+    /**
+     * Stop AR tracking and release resources
+     */
+    stop() {
+        if (this.controller) {
+            this.controller.dispose();
+            this.controller = null;
+        }
+        if (this.video && this.video.srcObject) {
+            this.video.srcObject.getTracks().forEach(track => track.stop());
+            this.video.remove();
+            this.video = null;
+        }
+        this.isTracking = false;
+    }
+    _createVideo() {
+        this.video = document.createElement('video');
+        this.video.setAttribute('autoplay', '');
+        this.video.setAttribute('playsinline', '');
+        this.video.setAttribute('muted', '');
+        this.video.style.cssText = `
+      position: absolute;
+      top: 0;
+      left: 0;
+      width: 100%;
+      height: 100%;
+      object-fit: cover;
+      z-index: 0;
+    `;
+        this.container.style.position = 'relative';
+        this.container.style.overflow = 'hidden';
+        this.container.insertBefore(this.video, this.container.firstChild);
+    }
+    async _startCamera() {
+        const stream = await navigator.mediaDevices.getUserMedia({
+            video: this.cameraConfig
+        });
+        this.video.srcObject = stream;
+        await this.video.play();
+        // Wait for video dimensions to be available
+        await new Promise(resolve => {
+            if (this.video.videoWidth > 0)
+                return resolve();
+            this.video.onloadedmetadata = resolve;
+        });
+    }
+    _initController() {
+        this.controller = new Controller({
+            inputWidth: this.video.videoWidth,
+            inputHeight: this.video.videoHeight,
+            onUpdate: (data) => this._handleUpdate(data)
+        });
+    }
+    _handleUpdate(data) {
+        if (data.type !== 'updateMatrix')
+            return;
+        const { targetIndex, worldMatrix } = data;
+        if (worldMatrix) {
+            // Target found
+            if (!this.isTracking) {
+                this.isTracking = true;
+                this.overlay && (this.overlay.style.opacity = '1');
+                this.onFound && this.onFound({ targetIndex });
+            }
+            this.lastMatrix = worldMatrix;
+            this._positionOverlay(worldMatrix);
+            this.onUpdateCallback && this.onUpdateCallback({ targetIndex, worldMatrix });
+        }
+        else {
+            // Target lost
+            if (this.isTracking) {
+                this.isTracking = false;
+                this.overlay && (this.overlay.style.opacity = '0');
+                this.onLost && this.onLost({ targetIndex });
+            }
+        }
+    }
+    _positionOverlay(worldMatrix) {
+        if (!this.overlay)
+            return;
+        const containerRect = this.container.getBoundingClientRect();
+        const videoW = this.video.videoWidth;
+        const videoH = this.video.videoHeight;
+        // Calculate display area considering object-fit: cover
+        const containerAspect = containerRect.width / containerRect.height;
+        const videoAspect = videoW / videoH;
+        let displayW, displayH, offsetX, offsetY;
+        if (containerAspect > videoAspect) {
+            // Container is wider - video fills width, crops height
+            displayW = containerRect.width;
+            displayH = containerRect.width / videoAspect;
+            offsetX = 0;
+            offsetY = (containerRect.height - displayH) / 2;
+        }
+        else {
+            // Container is taller - video fills height, crops width  
+            displayH = containerRect.height;
+            displayW = containerRect.height * videoAspect;
+            offsetX = (containerRect.width - displayW) / 2;
+            offsetY = 0;
+        }
+        const scaleX = displayW / videoW;
+        const scaleY = displayH / videoH;
+        // Extract position and rotation from world matrix
+        // Matrix is column-major: [m0,m1,m2,m3, m4,m5,m6,m7, m8,m9,m10,m11, m12,m13,m14,m15]
+        const tx = worldMatrix[12];
+        const ty = worldMatrix[13];
+        const scale = Math.sqrt(worldMatrix[0] ** 2 + worldMatrix[1] ** 2);
+        const rotation = Math.atan2(worldMatrix[1], worldMatrix[0]);
+        // Convert from normalized coords to screen coords
+        const screenX = offsetX + (videoW / 2 + tx) * scaleX;
+        const screenY = offsetY + (videoH / 2 - ty) * scaleY;
+        // Apply transform
+        this.overlay.style.position = 'absolute';
+        this.overlay.style.transformOrigin = 'center center';
+        this.overlay.style.left = '0';
+        this.overlay.style.top = '0';
+        this.overlay.style.transform = `
+      translate(${screenX}px, ${screenY}px)
+      translate(-50%, -50%)
+      scale(${scale * scaleX * 0.01})
+      rotate(${-rotation}rad)
+    `;
+    }
+}
+export { SimpleAR };

package/dist/index.d.ts

@@ -1,2 +1,4 @@
 export * from "./react/types";
 export * from "./compiler/offline-compiler";
+export { Controller } from "./compiler/controller.js";
+export { SimpleAR } from "./compiler/simple-ar.js";

package/dist/index.js

@@ -1,2 +1,4 @@
 export * from "./react/types";
 export * from "./compiler/offline-compiler";
+export { Controller } from "./compiler/controller.js";
+export { SimpleAR } from "./compiler/simple-ar.js";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@srsergio/taptapp-ar",
-    "version": "1.0.11",
+    "version": "1.0.13",
     "description": "AR Compiler for Node.js and Browser",
     "repository": {
         "type": "git",
@@ -37,6 +37,20 @@
         "react-dom": ">=18.0.0",
         "three": ">=0.160.0"
     },
+    "peerDependenciesMeta": {
+        "aframe": {
+            "optional": true
+        },
+        "react": {
+            "optional": true
+        },
+        "react-dom": {
+            "optional": true
+        },
+        "three": {
+            "optional": true
+        }
+    },
     "dependencies": {
         "@msgpack/msgpack": "^3.0.0-beta2",
         "ml-matrix": "^6.10.4",

package/src/compiler/controller.js

@@ -91,32 +91,49 @@ class Controller {
     }
   }
 
-  addImageTargets(fileURL) {
-    return new Promise(async (resolve) => {
-      const content = await fetch(fileURL);
-      const buffer = await content.arrayBuffer();
-      const result = this.addImageTargetsFromBuffer(buffer);
-      resolve(result);
-    });
+  /**
+   * Load image targets from one or multiple .mind files
+   * @param {string|string[]} fileURLs - Single URL or array of URLs to .mind files
+   * @returns {Promise<{dimensions, matchingDataList, trackingDataList}>}
+   */
+  async addImageTargets(fileURLs) {
+    const urls = Array.isArray(fileURLs) ? fileURLs : [fileURLs];
+
+    // Fetch all .mind files in parallel
+    const buffers = await Promise.all(
+      urls.map(async (url) => {
+        const response = await fetch(url);
+        return response.arrayBuffer();
+      })
+    );
+
+    // Combine all buffers into a single target list
+    return this.addImageTargetsFromBuffers(buffers);
   }
 
-  addImageTargetsFromBuffer(buffer) {
-    const compiler = new Compiler();
-    const dataList = compiler.importData(buffer);
-
-    const trackingDataList = [];
-    const matchingDataList = [];
-    const dimensions = [];
-    for (let i = 0; i < dataList.length; i++) {
-      const item = dataList[i];
-      matchingDataList.push(item.matchingData);
-      trackingDataList.push(item.trackingData);
-      dimensions.push([item.targetImage.width, item.targetImage.height]);
+  /**
+   * Load image targets from multiple ArrayBuffers
+   * @param {ArrayBuffer[]} buffers - Array of .mind file buffers
+   */
+  addImageTargetsFromBuffers(buffers) {
+    const allTrackingData = [];
+    const allMatchingData = [];
+    const allDimensions = [];
+
+    for (const buffer of buffers) {
+      const compiler = new Compiler();
+      const dataList = compiler.importData(buffer);
+
+      for (const item of dataList) {
+        allMatchingData.push(item.matchingData);
+        allTrackingData.push(item.trackingData);
+        allDimensions.push([item.targetImage.width, item.targetImage.height]);
+      }
     }
 
     this.tracker = new Tracker(
-      dimensions,
-      trackingDataList,
+      allDimensions,
+      allTrackingData,
       this.projectionTransform,
       this.inputWidth,
       this.inputHeight,
@@ -131,12 +148,20 @@ class Controller {
         inputHeight: this.inputHeight,
         projectionTransform: this.projectionTransform,
         debugMode: this.debugMode,
-        matchingDataList,
+        matchingDataList: allMatchingData,
       });
     }
 
-    this.markerDimensions = dimensions;
-    return { dimensions, matchingDataList, trackingDataList };
+    this.markerDimensions = allDimensions;
+    return { dimensions: allDimensions, matchingDataList: allMatchingData, trackingDataList: allTrackingData };
+  }
+
+  /**
+   * Load image targets from a single ArrayBuffer (backward compatible)
+   * @param {ArrayBuffer} buffer - Single .mind file buffer
+   */
+  addImageTargetsFromBuffer(buffer) {
+    return this.addImageTargetsFromBuffers([buffer]);
   }
 
   dispose() {

package/src/compiler/simple-ar.js

@@ -0,0 +1,203 @@
+import { Controller } from "./controller.js";
+
+/**
+ * 🍦 SimpleAR - Dead-simple vanilla AR for image overlays
+ * 
+ * No Three.js. No A-Frame. Just HTML, CSS, and JavaScript.
+ * 
+ * @example
+ * const ar = new SimpleAR({
+ *   container: document.getElementById('ar-container'),
+ *   targetSrc: './my-target.mind',
+ *   overlay: document.getElementById('my-overlay'),
+ *   onFound: () => console.log('Target found!'),
+ *   onLost: () => console.log('Target lost!')
+ * });
+ * 
+ * await ar.start();
+ */
+class SimpleAR {
+    constructor({
+        container,
+        targetSrc,
+        overlay,
+        onFound = null,
+        onLost = null,
+        onUpdate = null,
+        cameraConfig = { facingMode: 'environment', width: 1280, height: 720 },
+    }) {
+        this.container = container;
+        this.targetSrc = targetSrc;
+        this.overlay = overlay;
+        this.onFound = onFound;
+        this.onLost = onLost;
+        this.onUpdateCallback = onUpdate;
+        this.cameraConfig = cameraConfig;
+
+        this.video = null;
+        this.controller = null;
+        this.isTracking = false;
+        this.lastMatrix = null;
+    }
+
+    /**
+   * Initialize and start AR tracking
+   */
+    async start() {
+        // 1. Create video element
+        this._createVideo();
+
+        // 2. Start camera
+        await this._startCamera();
+
+        // 3. Initialize controller
+        this._initController();
+
+        // 4. Load targets (supports single URL or array of URLs)
+        const targets = Array.isArray(this.targetSrc) ? this.targetSrc : [this.targetSrc];
+        await this.controller.addImageTargets(targets);
+        this.controller.processVideo(this.video);
+
+        return this;
+    }
+
+    /**
+     * Stop AR tracking and release resources
+     */
+    stop() {
+        if (this.controller) {
+            this.controller.dispose();
+            this.controller = null;
+        }
+        if (this.video && this.video.srcObject) {
+            this.video.srcObject.getTracks().forEach(track => track.stop());
+            this.video.remove();
+            this.video = null;
+        }
+        this.isTracking = false;
+    }
+
+    _createVideo() {
+        this.video = document.createElement('video');
+        this.video.setAttribute('autoplay', '');
+        this.video.setAttribute('playsinline', '');
+        this.video.setAttribute('muted', '');
+        this.video.style.cssText = `
+      position: absolute;
+      top: 0;
+      left: 0;
+      width: 100%;
+      height: 100%;
+      object-fit: cover;
+      z-index: 0;
+    `;
+        this.container.style.position = 'relative';
+        this.container.style.overflow = 'hidden';
+        this.container.insertBefore(this.video, this.container.firstChild);
+    }
+
+    async _startCamera() {
+        const stream = await navigator.mediaDevices.getUserMedia({
+            video: this.cameraConfig
+        });
+        this.video.srcObject = stream;
+        await this.video.play();
+
+        // Wait for video dimensions to be available
+        await new Promise(resolve => {
+            if (this.video.videoWidth > 0) return resolve();
+            this.video.onloadedmetadata = resolve;
+        });
+    }
+
+    _initController() {
+        this.controller = new Controller({
+            inputWidth: this.video.videoWidth,
+            inputHeight: this.video.videoHeight,
+            onUpdate: (data) => this._handleUpdate(data)
+        });
+    }
+
+    _handleUpdate(data) {
+        if (data.type !== 'updateMatrix') return;
+
+        const { targetIndex, worldMatrix } = data;
+
+        if (worldMatrix) {
+            // Target found
+            if (!this.isTracking) {
+                this.isTracking = true;
+                this.overlay && (this.overlay.style.opacity = '1');
+                this.onFound && this.onFound({ targetIndex });
+            }
+
+            this.lastMatrix = worldMatrix;
+            this._positionOverlay(worldMatrix);
+            this.onUpdateCallback && this.onUpdateCallback({ targetIndex, worldMatrix });
+
+        } else {
+            // Target lost
+            if (this.isTracking) {
+                this.isTracking = false;
+                this.overlay && (this.overlay.style.opacity = '0');
+                this.onLost && this.onLost({ targetIndex });
+            }
+        }
+    }
+
+    _positionOverlay(worldMatrix) {
+        if (!this.overlay) return;
+
+        const containerRect = this.container.getBoundingClientRect();
+        const videoW = this.video.videoWidth;
+        const videoH = this.video.videoHeight;
+
+        // Calculate display area considering object-fit: cover
+        const containerAspect = containerRect.width / containerRect.height;
+        const videoAspect = videoW / videoH;
+
+        let displayW, displayH, offsetX, offsetY;
+
+        if (containerAspect > videoAspect) {
+            // Container is wider - video fills width, crops height
+            displayW = containerRect.width;
+            displayH = containerRect.width / videoAspect;
+            offsetX = 0;
+            offsetY = (containerRect.height - displayH) / 2;
+        } else {
+            // Container is taller - video fills height, crops width  
+            displayH = containerRect.height;
+            displayW = containerRect.height * videoAspect;
+            offsetX = (containerRect.width - displayW) / 2;
+            offsetY = 0;
+        }
+
+        const scaleX = displayW / videoW;
+        const scaleY = displayH / videoH;
+
+        // Extract position and rotation from world matrix
+        // Matrix is column-major: [m0,m1,m2,m3, m4,m5,m6,m7, m8,m9,m10,m11, m12,m13,m14,m15]
+        const tx = worldMatrix[12];
+        const ty = worldMatrix[13];
+        const scale = Math.sqrt(worldMatrix[0] ** 2 + worldMatrix[1] ** 2);
+        const rotation = Math.atan2(worldMatrix[1], worldMatrix[0]);
+
+        // Convert from normalized coords to screen coords
+        const screenX = offsetX + (videoW / 2 + tx) * scaleX;
+        const screenY = offsetY + (videoH / 2 - ty) * scaleY;
+
+        // Apply transform
+        this.overlay.style.position = 'absolute';
+        this.overlay.style.transformOrigin = 'center center';
+        this.overlay.style.left = '0';
+        this.overlay.style.top = '0';
+        this.overlay.style.transform = `
+      translate(${screenX}px, ${screenY}px)
+      translate(-50%, -50%)
+      scale(${scale * scaleX * 0.01})
+      rotate(${-rotation}rad)
+    `;
+    }
+}
+
+export { SimpleAR };

package/src/index.ts

@@ -1,2 +1,4 @@
 export * from "./react/types";
 export * from "./compiler/offline-compiler";
+export { Controller } from "./compiler/controller.js";
+export { SimpleAR } from "./compiler/simple-ar.js";