@srsergio/taptapp-ar 1.0.12 → 1.0.14

package/README.md

@@ -134,7 +134,11 @@ const controller = new Controller({
   }
 });
 
+// Single target
 await controller.addImageTargets('./targets.mind');
+
+// OR multiple targets from different .mind files
+await controller.addImageTargets(['./target1.mind', './target2.mind', './target3.mind']);
 controller.processVideo(videoElement); // Starts the internal RAF loop
 ```
 
@@ -156,6 +160,59 @@ if (targetIndex !== -1) {
 }
 ```
 
+### 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:
 

package/dist/compiler/controller.d.ts

@@ -31,13 +31,36 @@ 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;
+    matchingDataList: any[] | 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[];
@@ -78,8 +101,18 @@ export class Controller {
     trackUpdate(modelViewTransform: any, trackFeatures: any): Promise<any>;
     _workerMatch(featurePoints: any, targetIndexes: any): Promise<any>;
     workerMatchDone: ((data: any) => void) | undefined;
+    _matchOnMainThread(featurePoints: any, targetIndexes: any): Promise<{
+        targetIndex: number;
+        modelViewTransform: number[][] | null;
+        debugExtra: {
+            frames: never[];
+        } | null;
+    }>;
+    mainThreadMatcher: import("./matching/matcher.js").Matcher | undefined;
+    mainThreadEstimator: import("./estimation/estimator.js").Estimator | undefined;
     _workerTrackUpdate(modelViewTransform: any, trackingFeatures: any): Promise<any>;
     workerTrackDone: ((data: any) => void) | undefined;
+    _trackUpdateOnMainThread(modelViewTransform: any, trackingFeatures: any): Promise<never[][] | null>;
     _glModelViewMatrix(modelViewTransform: any, targetIndex: any): any[];
     _glProjectionMatrix({ projectionTransform, width, height, near, far }: {
         projectionTransform: any;

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,19 @@ class Controller {
                 inputHeight: this.inputHeight,
                 projectionTransform: this.projectionTransform,
                 debugMode: this.debugMode,
-                matchingDataList,
+                matchingDataList: allMatchingData,
             });
         }
-        this.markerDimensions = dimensions;
-        return { dimensions, matchingDataList, trackingDataList };
+        this.markerDimensions = allDimensions;
+        this.matchingDataList = allMatchingData; // Store for main-thread fallback
+        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();
@@ -305,6 +325,11 @@ class Controller {
     }
     _workerMatch(featurePoints, targetIndexes) {
         return new Promise((resolve) => {
+            // If no worker available, process on main thread
+            if (!this.worker) {
+                this._matchOnMainThread(featurePoints, targetIndexes).then(resolve);
+                return;
+            }
             this.workerMatchDone = (data) => {
                 resolve({
                     targetIndex: data.targetIndex,
@@ -312,16 +337,51 @@ class Controller {
                     debugExtra: data.debugExtra,
                 });
             };
-            this.worker && this.worker.postMessage({ type: "match", featurePoints: featurePoints, targetIndexes });
+            this.worker.postMessage({ type: "match", featurePoints: featurePoints, targetIndexes });
         });
     }
+    async _matchOnMainThread(featurePoints, targetIndexes) {
+        // Lazy initialize Matcher and Estimator for main thread
+        if (!this.mainThreadMatcher) {
+            const { Matcher } = await import("./matching/matcher.js");
+            const { Estimator } = await import("./estimation/estimator.js");
+            this.mainThreadMatcher = new Matcher(this.inputWidth, this.inputHeight, this.debugMode);
+            this.mainThreadEstimator = new Estimator(this.projectionTransform);
+        }
+        let matchedTargetIndex = -1;
+        let matchedModelViewTransform = null;
+        let matchedDebugExtra = null;
+        for (let i = 0; i < targetIndexes.length; i++) {
+            const matchingIndex = targetIndexes[i];
+            const { keyframeIndex, screenCoords, worldCoords, debugExtra } = this.mainThreadMatcher.matchDetection(this.matchingDataList[matchingIndex], featurePoints);
+            matchedDebugExtra = debugExtra;
+            if (keyframeIndex !== -1) {
+                const modelViewTransform = this.mainThreadEstimator.estimate({ screenCoords, worldCoords });
+                if (modelViewTransform) {
+                    matchedTargetIndex = matchingIndex;
+                    matchedModelViewTransform = modelViewTransform;
+                }
+                break;
+            }
+        }
+        return {
+            targetIndex: matchedTargetIndex,
+            modelViewTransform: matchedModelViewTransform,
+            debugExtra: matchedDebugExtra,
+        };
+    }
     _workerTrackUpdate(modelViewTransform, trackingFeatures) {
         return new Promise((resolve) => {
+            // If no worker available, process on main thread
+            if (!this.worker) {
+                this._trackUpdateOnMainThread(modelViewTransform, trackingFeatures).then(resolve);
+                return;
+            }
             this.workerTrackDone = (data) => {
                 resolve(data.modelViewTransform);
             };
             const { worldCoords, screenCoords } = trackingFeatures;
-            this.worker && this.worker.postMessage({
+            this.worker.postMessage({
                 type: "trackUpdate",
                 modelViewTransform,
                 worldCoords,
@@ -329,6 +389,20 @@ class Controller {
             });
         });
     }
+    async _trackUpdateOnMainThread(modelViewTransform, trackingFeatures) {
+        // Lazy initialize Estimator for main thread
+        if (!this.mainThreadEstimator) {
+            const { Estimator } = await import("./estimation/estimator.js");
+            this.mainThreadEstimator = new Estimator(this.projectionTransform);
+        }
+        const { worldCoords, screenCoords } = trackingFeatures;
+        const finalModelViewTransform = this.mainThreadEstimator.refineEstimate({
+            initialModelViewTransform: modelViewTransform,
+            worldCoords,
+            screenCoords,
+        });
+        return finalModelViewTransform;
+    }
     _glModelViewMatrix(modelViewTransform, targetIndex) {
         const height = this.markerDimensions[targetIndex][1];
         const openGLWorldMatrix = [

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.12",
+    "version": "1.0.14",
     "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,21 @@ class Controller {
         inputHeight: this.inputHeight,
         projectionTransform: this.projectionTransform,
         debugMode: this.debugMode,
-        matchingDataList,
+        matchingDataList: allMatchingData,
       });
     }
 
-    this.markerDimensions = dimensions;
-    return { dimensions, matchingDataList, trackingDataList };
+    this.markerDimensions = allDimensions;
+    this.matchingDataList = allMatchingData; // Store for main-thread fallback
+    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() {
@@ -370,6 +396,12 @@ class Controller {
 
   _workerMatch(featurePoints, targetIndexes) {
     return new Promise((resolve) => {
+      // If no worker available, process on main thread
+      if (!this.worker) {
+        this._matchOnMainThread(featurePoints, targetIndexes).then(resolve);
+        return;
+      }
+
       this.workerMatchDone = (data) => {
         resolve({
           targetIndex: data.targetIndex,
@@ -377,17 +409,63 @@ class Controller {
           debugExtra: data.debugExtra,
         });
       };
-      this.worker && this.worker.postMessage({ type: "match", featurePoints: featurePoints, targetIndexes });
+      this.worker.postMessage({ type: "match", featurePoints: featurePoints, targetIndexes });
     });
   }
 
+  async _matchOnMainThread(featurePoints, targetIndexes) {
+    // Lazy initialize Matcher and Estimator for main thread
+    if (!this.mainThreadMatcher) {
+      const { Matcher } = await import("./matching/matcher.js");
+      const { Estimator } = await import("./estimation/estimator.js");
+      this.mainThreadMatcher = new Matcher(this.inputWidth, this.inputHeight, this.debugMode);
+      this.mainThreadEstimator = new Estimator(this.projectionTransform);
+    }
+
+    let matchedTargetIndex = -1;
+    let matchedModelViewTransform = null;
+    let matchedDebugExtra = null;
+
+    for (let i = 0; i < targetIndexes.length; i++) {
+      const matchingIndex = targetIndexes[i];
+
+      const { keyframeIndex, screenCoords, worldCoords, debugExtra } = this.mainThreadMatcher.matchDetection(
+        this.matchingDataList[matchingIndex],
+        featurePoints,
+      );
+      matchedDebugExtra = debugExtra;
+
+      if (keyframeIndex !== -1) {
+        const modelViewTransform = this.mainThreadEstimator.estimate({ screenCoords, worldCoords });
+
+        if (modelViewTransform) {
+          matchedTargetIndex = matchingIndex;
+          matchedModelViewTransform = modelViewTransform;
+        }
+        break;
+      }
+    }
+
+    return {
+      targetIndex: matchedTargetIndex,
+      modelViewTransform: matchedModelViewTransform,
+      debugExtra: matchedDebugExtra,
+    };
+  }
+
   _workerTrackUpdate(modelViewTransform, trackingFeatures) {
     return new Promise((resolve) => {
+      // If no worker available, process on main thread
+      if (!this.worker) {
+        this._trackUpdateOnMainThread(modelViewTransform, trackingFeatures).then(resolve);
+        return;
+      }
+
       this.workerTrackDone = (data) => {
         resolve(data.modelViewTransform);
       };
       const { worldCoords, screenCoords } = trackingFeatures;
-      this.worker && this.worker.postMessage({
+      this.worker.postMessage({
         type: "trackUpdate",
         modelViewTransform,
         worldCoords,
@@ -396,6 +474,22 @@ class Controller {
     });
   }
 
+  async _trackUpdateOnMainThread(modelViewTransform, trackingFeatures) {
+    // Lazy initialize Estimator for main thread
+    if (!this.mainThreadEstimator) {
+      const { Estimator } = await import("./estimation/estimator.js");
+      this.mainThreadEstimator = new Estimator(this.projectionTransform);
+    }
+
+    const { worldCoords, screenCoords } = trackingFeatures;
+    const finalModelViewTransform = this.mainThreadEstimator.refineEstimate({
+      initialModelViewTransform: modelViewTransform,
+      worldCoords,
+      screenCoords,
+    });
+    return finalModelViewTransform;
+  }
+
   _glModelViewMatrix(modelViewTransform, targetIndex) {
     const height = this.markerDimensions[targetIndex][1];
 

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";