@srsergio/taptapp-ar 1.0.78 → 1.0.80

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio Lázaro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+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.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+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

@@ -1,11 +1,32 @@
 # @srsergio/taptapp-ar
 
+[![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)
+[![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.
 
 **100% Pure JavaScript**: This package is now completely independent of **TensorFlow.js** for both compilation and real-time tracking, resulting in massive performance gains and zero-latency initialization.
 
 ---
 
+## 📖 Table of Contents
+- [🌟 Key Features](#-key-features)
+- [🛠 Installation](#-installation)
+- [📊 Industry-Leading Benchmarks](#-industry-leading-benchmarks-v7-moonshot)
+- [🛡️ Robustness & Stability](#️-robustness--stability-stress-tested)
+- [🖼️ Compiler Usage](#️-compiler-usage-nodejs--web)
+- [🎥 Runtime Usage](#-runtime-usage-ar-tracking)
+  - [A-Frame Integration](#1-simple-a-frame-integration)
+  - [Three.js Wrapper](#2-high-performance-threejs-wrapper)
+  - [Raw Controller](#3-raw-controller-advanced--custom-engines)
+  - [Vanilla JS (SimpleAR)](#4-vanilla-js-no-framework-)
+- [🏗️ Protocol V7](#️-protocol-v7-moonshot-packed-format)
+- [📄 License & Credits](#-license--credits)
+
+---
+
 ## 🌟 Key Features
 
 - 🖼️ **Hyper-Fast Compiler**: Pure JavaScript compiler that generates `.taar` files in **< 3s**.

package/dist/compiler/controller.d.ts

@@ -1,6 +1,7 @@
 import { Tracker } from "./tracker/tracker.js";
 import { InputLoader } from "./input-loader.js";
 import { FeatureManager } from "./features/feature-manager.js";
+import { DetectorLite } from "./detector/detector-lite.js";
 export interface ControllerOptions {
     inputWidth: number;
     inputHeight: number;
@@ -34,6 +35,7 @@ declare class Controller {
     mainThreadMatcher: any;
     mainThreadEstimator: any;
     featureManager: FeatureManager;
+    fullDetector: DetectorLite | null;
     constructor({ inputWidth, inputHeight, onUpdate, debugMode, maxTrack, warmupTolerance, missTolerance, filterMinCF, filterBeta, worker, }: ControllerOptions);
     _setupWorkerListener(): void;
     _ensureWorker(): void;
@@ -61,16 +63,20 @@ declare class Controller {
         targetIndex: any;
         modelViewTransform: any;
     }>;
-    _trackAndUpdate(inputData: any, lastModelViewTransform: number[][], targetIndex: number): Promise<any>;
+    _trackAndUpdate(inputData: any, lastModelViewTransform: number[][], targetIndex: number): Promise<{
+        modelViewTransform: any;
+        screenCoords: {
+            x: number;
+            y: number;
+        }[];
+        reliabilities: number[];
+        stabilities: any[];
+    }>;
     processVideo(input: any): void;
     stopProcessVideo(): void;
     detect(input: any): Promise<{
         featurePoints: any[];
-        debugExtra: {
-            projectedImage: number[];
-        } | {
-            projectedImage?: undefined;
-        };
+        debugExtra: {};
     }>;
     match(featurePoints: any, targetIndex: number): Promise<{
         targetIndex: any;
@@ -80,6 +86,13 @@ declare class Controller {
         debugExtra: any;
     }>;
     track(input: any, modelViewTransform: number[][], targetIndex: number): Promise<{
+        worldCoords: never[];
+        screenCoords: never[];
+        reliabilities: never[];
+        debugExtra: {};
+        indices?: undefined;
+        octaveIndex?: undefined;
+    } | {
         worldCoords: {
             x: number;
             y: number;
@@ -89,6 +102,9 @@ declare class Controller {
             x: number;
             y: number;
         }[];
+        reliabilities: number[];
+        indices: number[];
+        octaveIndex: any;
         debugExtra: {};
     }>;
     trackUpdate(modelViewTransform: number[][], trackFeatures: any): Promise<any>;

package/dist/compiler/controller.js

@@ -5,7 +5,7 @@ import { FeatureManager } from "./features/feature-manager.js";
 import { OneEuroFilterFeature } from "./features/one-euro-filter-feature.js";
 import { TemporalFilterFeature } from "./features/temporal-filter-feature.js";
 import { AutoRotationFeature } from "./features/auto-rotation-feature.js";
-import { CropDetectionFeature } from "./features/crop-detection-feature.js";
+import { DetectorLite } from "./detector/detector-lite.js";
 let ControllerWorker;
 // Conditional import for worker to avoid crash in non-vite environments
 const getControllerWorker = async () => {
@@ -24,7 +24,9 @@ ControllerWorker = await getControllerWorker();
 const DEFAULT_FILTER_CUTOFF = 0.5;
 const DEFAULT_FILTER_BETA = 0.1;
 const DEFAULT_WARMUP_TOLERANCE = 2; // Instant detection
-const DEFAULT_MISS_TOLERANCE = 5; // More grace when partially hidden
+const DEFAULT_MISS_TOLERANCE = 1; // Immediate response to tracking loss
+const WORKER_TIMEOUT_MS = 1000; // Prevent worker hangs from killing the loop
+let loopIdCounter = 0;
 class Controller {
     inputWidth;
     inputHeight;
@@ -46,6 +48,7 @@ class Controller {
     mainThreadMatcher;
     mainThreadEstimator;
     featureManager;
+    fullDetector = null;
     constructor({ inputWidth, inputHeight, onUpdate = null, debugMode = false, maxTrack = 1, warmupTolerance = null, missTolerance = null, filterMinCF = null, filterBeta = null, worker = null, }) {
         this.inputWidth = inputWidth;
         this.inputHeight = inputHeight;
@@ -54,13 +57,15 @@ class Controller {
         this.featureManager.addFeature(new OneEuroFilterFeature(filterMinCF === null ? DEFAULT_FILTER_CUTOFF : filterMinCF, filterBeta === null ? DEFAULT_FILTER_BETA : filterBeta));
         this.featureManager.addFeature(new TemporalFilterFeature(warmupTolerance === null ? DEFAULT_WARMUP_TOLERANCE : warmupTolerance, missTolerance === null ? DEFAULT_MISS_TOLERANCE : missTolerance));
         this.featureManager.addFeature(new AutoRotationFeature());
-        this.featureManager.addFeature(new CropDetectionFeature());
+        // User wants "sin recortes", so we don't add CropDetectionFeature
         this.inputLoader = new InputLoader(this.inputWidth, this.inputHeight);
         this.onUpdate = onUpdate;
         this.debugMode = debugMode;
         this.worker = worker;
         if (this.worker)
             this._setupWorkerListener();
+        // Moonshot: Full frame detector for better sensitivity
+        this.fullDetector = new DetectorLite(this.inputWidth, this.inputHeight, { useLSH: true });
         this.featureManager.init({
             inputWidth: this.inputWidth,
             inputHeight: this.inputHeight,
@@ -160,8 +165,7 @@ class Controller {
     }
     dummyRun(input) {
         const inputData = this.inputLoader.loadInput(input);
-        const cropFeature = this.featureManager.getFeature("crop-detection");
-        cropFeature?.detect(inputData, false);
+        this.fullDetector?.detect(inputData);
         this.tracker.dummyRun(inputData);
     }
     getProjectionMatrix() {
@@ -179,25 +183,67 @@ class Controller {
         return this._glModelViewMatrix(modelViewTransform, targetIndex);
     }
     async _detectAndMatch(inputData, targetIndexes) {
-        const cropFeature = this.featureManager.getFeature("crop-detection");
-        const { featurePoints } = cropFeature.detect(inputData, true);
+        const { featurePoints } = this.fullDetector.detect(inputData);
         const { targetIndex: matchedTargetIndex, modelViewTransform } = await this._workerMatch(featurePoints, targetIndexes);
         return { targetIndex: matchedTargetIndex, modelViewTransform };
     }
     async _trackAndUpdate(inputData, lastModelViewTransform, targetIndex) {
-        const { worldCoords, screenCoords } = this.tracker.track(inputData, lastModelViewTransform, targetIndex);
-        if (worldCoords.length < 8)
-            return null; // Resynced with Matcher (8 points) to allow initial detection
+        const { worldCoords, screenCoords, reliabilities, indices = [], octaveIndex = 0 } = this.tracker.track(inputData, lastModelViewTransform, targetIndex);
+        const state = this.trackingStates[targetIndex];
+        if (!state.pointStabilities)
+            state.pointStabilities = [];
+        if (!state.pointStabilities[octaveIndex]) {
+            // Initialize stabilities for this octave if not exists
+            const numPoints = this.tracker.prebuiltData[targetIndex][octaveIndex].px.length;
+            state.pointStabilities[octaveIndex] = new Float32Array(numPoints).fill(0.5); // Start at 0.5
+        }
+        const stabilities = state.pointStabilities[octaveIndex];
+        const currentStabilities = [];
+        // Update all points in this octave
+        for (let i = 0; i < stabilities.length; i++) {
+            const isTracked = indices.includes(i);
+            if (isTracked) {
+                stabilities[i] = Math.min(1.0, stabilities[i] + 0.35); // Fast recovery (approx 3 frames)
+            }
+            else {
+                stabilities[i] = Math.max(0.0, stabilities[i] - 0.12); // Slightly more forgiving loss
+            }
+        }
+        // Collect stabilities and FILTER OUT excessive flickerers (Dead Zone)
+        const filteredWorldCoords = [];
+        const filteredScreenCoords = [];
+        const filteredStabilities = [];
+        for (let i = 0; i < indices.length; i++) {
+            const s = stabilities[indices[i]];
+            if (s > 0.3) { // Hard Cutoff: points with <30% stability are ignored
+                filteredWorldCoords.push(worldCoords[i]);
+                filteredScreenCoords.push(screenCoords[i]);
+                filteredStabilities.push(s);
+            }
+        }
+        // STRICT QUALITY CHECK: Prevent "sticky" tracking on background noise.
+        // We require a minimum number of high-confidence AND STABLE points.
+        const stableAndReliable = reliabilities.filter((r, idx) => r > 0.75 && stabilities[indices[idx]] > 0.5).length;
+        if (stableAndReliable < 6 || filteredWorldCoords.length < 8) {
+            return { modelViewTransform: null, screenCoords: [], reliabilities: [], stabilities: [] };
+        }
         const modelViewTransform = await this._workerTrackUpdate(lastModelViewTransform, {
-            worldCoords,
-            screenCoords,
+            worldCoords: filteredWorldCoords,
+            screenCoords: filteredScreenCoords,
+            stabilities: filteredStabilities
         });
-        return modelViewTransform;
+        return {
+            modelViewTransform,
+            screenCoords: filteredScreenCoords,
+            reliabilities: reliabilities.filter((_, idx) => stabilities[indices[idx]] > 0.3),
+            stabilities: filteredStabilities
+        };
     }
     processVideo(input) {
         if (this.processingVideo)
             return;
         this.processingVideo = true;
+        const currentLoopId = ++loopIdCounter; // Added for ghost loop prevention
         this.trackingStates = [];
         for (let i = 0; i < (this.markerDimensions?.length || 0); i++) {
             this.trackingStates.push({
@@ -210,7 +256,7 @@ class Controller {
         }
         const startProcessing = async () => {
             while (true) {
-                if (!this.processingVideo)
+                if (!this.processingVideo || currentLoopId !== loopIdCounter)
                     break;
                 const inputData = this.inputLoader.loadInput(input);
                 const nTracking = this.trackingStates.reduce((acc, s) => acc + (!!s.isTracking ? 1 : 0), 0);
@@ -233,12 +279,18 @@ class Controller {
                 for (let i = 0; i < this.trackingStates.length; i++) {
                     const trackingState = this.trackingStates[i];
                     if (trackingState.isTracking) {
-                        let modelViewTransform = await this._trackAndUpdate(inputData, trackingState.currentModelViewTransform, i);
-                        if (modelViewTransform === null) {
+                        const result = await this._trackAndUpdate(inputData, trackingState.currentModelViewTransform, i);
+                        if (result === null || result.modelViewTransform === null) {
                             trackingState.isTracking = false;
+                            trackingState.screenCoords = [];
+                            trackingState.reliabilities = [];
+                            trackingState.stabilities = [];
                         }
                         else {
-                            trackingState.currentModelViewTransform = modelViewTransform;
+                            trackingState.currentModelViewTransform = result.modelViewTransform;
+                            trackingState.screenCoords = result.screenCoords;
+                            trackingState.reliabilities = result.reliabilities;
+                            trackingState.stabilities = result.stabilities;
                         }
                     }
                     const wasShowing = trackingState.showing;
@@ -250,7 +302,12 @@ class Controller {
                     }
                     if (trackingState.showing) {
                         const worldMatrix = this._glModelViewMatrix(trackingState.currentModelViewTransform, i);
-                        const filteredMatrix = this.featureManager.applyWorldMatrixFilters(i, worldMatrix);
+                        // Calculate confidence score based on point stability
+                        const stabilities = trackingState.stabilities || [];
+                        const avgStability = stabilities.length > 0
+                            ? stabilities.reduce((a, b) => a + b, 0) / stabilities.length
+                            : 0;
+                        const filteredMatrix = this.featureManager.applyWorldMatrixFilters(i, worldMatrix, { stability: avgStability });
                         trackingState.trackingMatrix = filteredMatrix;
                         let finalMatrix = [...filteredMatrix];
                         const isInputRotated = input.width === this.inputHeight && input.height === this.inputWidth;
@@ -264,7 +321,10 @@ class Controller {
                             type: "updateMatrix",
                             targetIndex: i,
                             worldMatrix: finalMatrix,
-                            modelViewTransform: trackingState.currentModelViewTransform
+                            modelViewTransform: trackingState.currentModelViewTransform,
+                            screenCoords: trackingState.screenCoords,
+                            reliabilities: trackingState.reliabilities,
+                            stabilities: trackingState.stabilities
                         });
                     }
                 }
@@ -284,9 +344,8 @@ class Controller {
     }
     async detect(input) {
         const inputData = this.inputLoader.loadInput(input);
-        const cropFeature = this.featureManager.getFeature("crop-detection");
-        const { featurePoints, debugExtra } = cropFeature.detect(inputData, false);
-        return { featurePoints, debugExtra };
+        const { featurePoints } = this.fullDetector.detect(inputData);
+        return { featurePoints, debugExtra: {} };
     }
     async match(featurePoints, targetIndex) {
         const { targetIndex: matchedTargetIndex, modelViewTransform, screenCoords, worldCoords, debugExtra } = await this._workerMatch(featurePoints, [
@@ -306,10 +365,16 @@ class Controller {
     _workerMatch(featurePoints, targetIndexes) {
         return new Promise((resolve) => {
             if (!this.worker) {
-                this._matchOnMainThread(featurePoints, targetIndexes).then(resolve);
+                this._matchOnMainThread(featurePoints, targetIndexes).then(resolve).catch(() => resolve({ targetIndex: -1 }));
                 return;
             }
+            const timeout = setTimeout(() => {
+                this.workerMatchDone = null;
+                resolve({ targetIndex: -1 });
+            }, WORKER_TIMEOUT_MS);
             this.workerMatchDone = (data) => {
+                clearTimeout(timeout);
+                this.workerMatchDone = null;
                 resolve({
                     targetIndex: data.targetIndex,
                     modelViewTransform: data.modelViewTransform,
@@ -359,18 +424,25 @@ class Controller {
     _workerTrackUpdate(modelViewTransform, trackingFeatures) {
         return new Promise((resolve) => {
             if (!this.worker) {
-                this._trackUpdateOnMainThread(modelViewTransform, trackingFeatures).then(resolve);
+                this._trackUpdateOnMainThread(modelViewTransform, trackingFeatures).then(resolve).catch(() => resolve(null));
                 return;
             }
+            const timeout = setTimeout(() => {
+                this.workerTrackDone = null;
+                resolve(null);
+            }, WORKER_TIMEOUT_MS);
             this.workerTrackDone = (data) => {
+                clearTimeout(timeout);
+                this.workerTrackDone = null;
                 resolve(data.modelViewTransform);
             };
-            const { worldCoords, screenCoords } = trackingFeatures;
+            const { worldCoords, screenCoords, stabilities } = trackingFeatures;
             this.worker.postMessage({
                 type: "trackUpdate",
                 modelViewTransform,
                 worldCoords,
                 screenCoords,
+                stabilities
             });
         });
     }
@@ -379,11 +451,12 @@ class Controller {
             const { Estimator } = await import("./estimation/estimator.js");
             this.mainThreadEstimator = new Estimator(this.projectionTransform);
         }
-        const { worldCoords, screenCoords } = trackingFeatures;
+        const { worldCoords, screenCoords, stabilities } = trackingFeatures;
         return this.mainThreadEstimator.refineEstimate({
             initialModelViewTransform: modelViewTransform,
             worldCoords,
             screenCoords,
+            stabilities
         });
     }
     _glModelViewMatrix(modelViewTransform, targetIndex) {

package/dist/compiler/controller.worker.js

@@ -39,11 +39,12 @@ onmessage = (msg) => {
             });
             break;
         case "trackUpdate":
-            const { modelViewTransform, worldCoords, screenCoords } = data;
+            const { modelViewTransform, worldCoords, screenCoords, stabilities } = data;
             const finalModelViewTransform = estimator.refineEstimate({
                 initialModelViewTransform: modelViewTransform,
                 worldCoords,
                 screenCoords,
+                stabilities, // Stability-based weights
             });
             postMessage({
                 type: "trackUpdateDone",

package/dist/compiler/estimation/refine-estimate.d.ts

@@ -1,6 +1,7 @@
-export function refineEstimate({ initialModelViewTransform, projectionTransform, worldCoords, screenCoords, }: {
+export function refineEstimate({ initialModelViewTransform, projectionTransform, worldCoords, screenCoords, stabilities, }: {
     initialModelViewTransform: any;
     projectionTransform: any;
     worldCoords: any;
     screenCoords: any;
+    stabilities: any;
 }): never[][] | null;

package/dist/compiler/estimation/refine-estimate.js

@@ -9,7 +9,8 @@ const ICP_BREAK_LOOP_ERROR_RATIO_THRESH = 0.99;
 let mat = [[], [], []];
 let J_U_Xc = [[], []]; // 2x3
 let J_Xc_S = [[], [], []]; // 3x6
-const refineEstimate = ({ initialModelViewTransform, projectionTransform, worldCoords, screenCoords, }) => {
+const refineEstimate = ({ initialModelViewTransform, projectionTransform, worldCoords, screenCoords, stabilities, // Stability-based weighting
+ }) => {
     // Question: shall we normlize the screen coords as well?
     // Question: do we need to normlize the scale as well, i.e. make coords from -1 to 1
     //
@@ -59,6 +60,7 @@ const refineEstimate = ({ initialModelViewTransform, projectionTransform, worldC
             projectionTransform,
             worldCoords: normalizedWorldCoords,
             screenCoords,
+            stabilities, // Pass weights to ICP
             inlierProb: inlierProbs[i],
         });
         updatedModelViewTransform = ret.modelViewTransform;
@@ -87,7 +89,7 @@ const refineEstimate = ({ initialModelViewTransform, projectionTransform, worldC
 };
 // ICP iteration
 // Question: can someone provide theoretical reference / mathematical proof for the following computations?
-const _doICP = ({ initialModelViewTransform, projectionTransform, worldCoords, screenCoords, inlierProb, }) => {
+const _doICP = ({ initialModelViewTransform, projectionTransform, worldCoords, screenCoords, stabilities, inlierProb, }) => {
     const isRobustMode = inlierProb < 1;
     let modelViewTransform = initialModelViewTransform;
     let err0 = 0.0;
@@ -152,7 +154,11 @@ const _doICP = ({ initialModelViewTransform, projectionTransform, worldCoords, s
                 worldCoord: worldCoords[n],
             });
             if (isRobustMode) {
-                const W = (1.0 - E[n] / K2) * (1.0 - E[n] / K2);
+                const robustW = (1.0 - E[n] / K2) * (1.0 - E[n] / K2);
+                // Log-weighted stability: suppresses vibrators aggressively but allows recovery
+                const s = stabilities ? stabilities[n] : 1.0;
+                const stabilityW = s * Math.log10(9 * s + 1);
+                const W = robustW * stabilityW;
                 for (let j = 0; j < 2; j++) {
                     for (let i = 0; i < 6; i++) {
                         J_U_S[j][i] *= W;
@@ -162,8 +168,15 @@ const _doICP = ({ initialModelViewTransform, projectionTransform, worldCoords, s
                 dU.push([dys[n] * W]);
             }
             else {
-                dU.push([dxs[n]]);
-                dU.push([dys[n]]);
+                const s = stabilities ? stabilities[n] : 1.0;
+                const W = s * Math.log10(9 * s + 1);
+                for (let j = 0; j < 2; j++) {
+                    for (let i = 0; i < 6; i++) {
+                        J_U_S[j][i] *= W;
+                    }
+                }
+                dU.push([dxs[n] * W]);
+                dU.push([dys[n] * W]);
             }
             for (let i = 0; i < J_U_S.length; i++) {
                 allJ_U_S.push(J_U_S[i]);

package/dist/compiler/features/feature-base.d.ts

@@ -38,7 +38,7 @@ export interface ControllerFeature extends Feature {
     /**
      * Hook to filter or modify the final world matrix
      */
-    filterWorldMatrix?(targetIndex: number, worldMatrix: number[]): number[];
+    filterWorldMatrix?(targetIndex: number, worldMatrix: number[], context?: any): number[];
     /**
      * Hook to decide if a target should be shown
      */

package/dist/compiler/features/feature-manager.d.ts

@@ -5,7 +5,7 @@ export declare class FeatureManager {
     getFeature<T extends ControllerFeature>(id: string): T | undefined;
     init(context: FeatureContext): void;
     beforeProcess(inputData: any): void;
-    applyWorldMatrixFilters(targetIndex: number, worldMatrix: number[]): number[];
+    applyWorldMatrixFilters(targetIndex: number, worldMatrix: number[], context?: any): number[];
     shouldShow(targetIndex: number, isTracking: boolean): boolean;
     notifyUpdate(data: any): void;
     dispose(): void;

package/dist/compiler/features/feature-manager.js

@@ -20,11 +20,11 @@ export class FeatureManager {
             }
         }
     }
-    applyWorldMatrixFilters(targetIndex, worldMatrix) {
+    applyWorldMatrixFilters(targetIndex, worldMatrix, context) {
         let result = worldMatrix;
         for (const feature of this.features) {
             if (feature.enabled && feature.filterWorldMatrix) {
-                result = feature.filterWorldMatrix(targetIndex, result);
+                result = feature.filterWorldMatrix(targetIndex, result, context);
             }
         }
         return result;

package/dist/compiler/features/one-euro-filter-feature.d.ts

@@ -10,6 +10,6 @@ export declare class OneEuroFilterFeature implements ControllerFeature {
     constructor(minCutOff?: number, beta?: number);
     init(context: FeatureContext): void;
     private getFilter;
-    filterWorldMatrix(targetIndex: number, worldMatrix: number[]): number[];
+    filterWorldMatrix(targetIndex: number, worldMatrix: number[], context?: any): number[];
     onUpdate(data: any): void;
 }

package/dist/compiler/features/one-euro-filter-feature.js

@@ -23,10 +23,17 @@ export class OneEuroFilterFeature {
         }
         return this.filters[targetIndex];
     }
-    filterWorldMatrix(targetIndex, worldMatrix) {
+    filterWorldMatrix(targetIndex, worldMatrix, context) {
         if (!this.enabled)
             return worldMatrix;
         const filter = this.getFilter(targetIndex);
+        const stability = context?.stability ?? 1.0;
+        // Dynamic Cutoff: If points are very stable (1.0), use higher cutoff (less responsiveness loss).
+        // If points are unstable (0.3), use much lower cutoff (heavy smoothing).
+        // We use a squared curve for even more aggressive suppression of jitter on unstable points.
+        const dynamicMinCutOff = this.minCutOff * (0.05 + Math.pow(stability, 2) * 0.95);
+        filter.minCutOff = dynamicMinCutOff;
+        filter.beta = this.beta;
         return filter.filter(Date.now(), worldMatrix);
     }
     onUpdate(data) {

package/dist/compiler/matching/matching.js

@@ -203,7 +203,7 @@ const _query = ({ node, descriptors, querypoint, queue, keypointIndexes, numPop
             queue.push({ node: childrenOrIndices[i], d: dist });
         }
         else {
-            _query({ node: childrenOrIndices[i], descriptors, querypoint, queue, keypointIndexes, numPop });
+            _query({ node: childrenOrIndices[i], descriptors, querypoint, queue, keypointIndexes, numPop: numPop + 1 });
         }
     }
     if (numPop < CLUSTER_MAX_POP && queue.length > 0) {

package/dist/compiler/offline-compiler.d.ts

@@ -5,26 +5,110 @@
  * que NO depende de TensorFlow, eliminando todos los problemas de
  * inicialización, bloqueos y compatibilidad.
  */
-import { WorkerPool } from "./utils/worker-pool.js";
 export declare class OfflineCompiler {
     data: any;
-    workerPool: WorkerPool | null;
     constructor();
-    _initNodeWorkers(): Promise<void>;
     compileImageTargets(images: any[], progressCallback: (p: number) => void): Promise<any>;
-    _compileTarget(targetImages: any[], progressCallback: (p: number) => void): Promise<any[]>;
-    _compileMatch(targetImages: any[], progressCallback: (p: number) => void): Promise<any[]>;
-    _compileTrack(targetImages: any[], progressCallback: (p: number) => void): Promise<any[]>;
+    _compileTarget(targetImages: any[], progressCallback: (p: number) => void): Promise<{
+        matchingData: {
+            maximaPoints: any[];
+            minimaPoints: any[];
+            maximaPointsCluster: {
+                rootNode: {
+                    leaf: boolean;
+                    pointIndexes: never[];
+                    centerPointIndex: null;
+                };
+            } | {
+                rootNode: {
+                    centerPointIndex: any;
+                };
+            };
+            minimaPointsCluster: {
+                rootNode: {
+                    leaf: boolean;
+                    pointIndexes: never[];
+                    centerPointIndex: null;
+                };
+            } | {
+                rootNode: {
+                    centerPointIndex: any;
+                };
+            };
+            width: any;
+            height: any;
+            scale: any;
+        }[];
+        trackingData: Object[];
+    }[]>;
+    _compileMatch(targetImages: any[], progressCallback: (p: number) => void): Promise<{
+        maximaPoints: any[];
+        minimaPoints: any[];
+        maximaPointsCluster: {
+            rootNode: {
+                leaf: boolean;
+                pointIndexes: never[];
+                centerPointIndex: null;
+            };
+        } | {
+            rootNode: {
+                centerPointIndex: any;
+            };
+        };
+        minimaPointsCluster: {
+            rootNode: {
+                leaf: boolean;
+                pointIndexes: never[];
+                centerPointIndex: null;
+            };
+        } | {
+            rootNode: {
+                centerPointIndex: any;
+            };
+        };
+        width: any;
+        height: any;
+        scale: any;
+    }[][]>;
+    _compileTrack(targetImages: any[], progressCallback: (p: number) => void): Promise<Object[][]>;
     compileTrack({ progressCallback, targetImages, basePercent }: {
         progressCallback: (p: number) => void;
         targetImages: any[];
         basePercent?: number;
-    }): Promise<any[]>;
+    }): Promise<Object[][]>;
     compileMatch({ progressCallback, targetImages, basePercent }: {
         progressCallback: (p: number) => void;
         targetImages: any[];
         basePercent?: number;
-    }): Promise<any[]>;
+    }): Promise<{
+        maximaPoints: any[];
+        minimaPoints: any[];
+        maximaPointsCluster: {
+            rootNode: {
+                leaf: boolean;
+                pointIndexes: never[];
+                centerPointIndex: null;
+            };
+        } | {
+            rootNode: {
+                centerPointIndex: any;
+            };
+        };
+        minimaPointsCluster: {
+            rootNode: {
+                leaf: boolean;
+                pointIndexes: never[];
+                centerPointIndex: null;
+            };
+        } | {
+            rootNode: {
+                centerPointIndex: any;
+            };
+        };
+        width: any;
+        height: any;
+        scale: any;
+    }[][]>;
     exportData(): Uint8Array<ArrayBuffer>;
     _getMorton(x: number, y: number): number;
     _columnarize(points: any[], tree: any, width: number, height: number): {