@srsergio/taptapp-ar 1.0.53 → 1.0.55

package/README.md

@@ -131,12 +131,57 @@ ar.stop();
 | `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 }`) |
+| `onUpdate` | ❌ | Called cada frame con `{ targetIndex, worldMatrix }` |
+| `cameraConfig` | ❌ | Config de cámara (por defecto: `{ facingMode: 'environment', width: 1280, height: 720 }`) |
 
 ---
 
-### 2. Raw Controller (Advanced & Custom Engines)
+### 2. React Integration (Vite & SSR Safe) ⚛️
+
+The fastest and most modern way to build AR apps with React. It supports **Code Splitting** and is **100% SSR-Safe** (Next.js, Astro, Remix).
+
+#### 🚀 Quick Start: `<TaptappAR />`
+Drop the component into your app. It handles camera permissions, scanning animations, and video/image overlays automatically.
+
+```tsx
+import { TaptappAR, mapDataToPropsConfig } from '@srsergio/taptapp-ar';
+
+const MyARComponent = ({ data }) => {
+  // mapDataToPropsConfig helps you format your data for the component
+  const config = mapDataToPropsConfig(data);
+
+  return (
+    <div style={{ width: '100vw', height: '100vh' }}>
+      <TaptappAR config={config} />
+    </div>
+  );
+};
+```
+
+#### 🛠️ Custom UI: `useAR()` Hook
+If you want to build your own UI while keeping the powerful tracking logic:
+
+```tsx
+import { useAR } from '@srsergio/taptapp-ar';
+
+const CustomAR = ({ config }) => {
+  const { containerRef, overlayRef, status, toggleVideo } = useAR(config);
+
+  return (
+    <div ref={containerRef} style={{ position: 'relative' }} onClick={toggleVideo}>
+      {/* Custom Scanning UI */}
+      {status === 'scanning' && <div className="my-loader">Scanning...</div>}
+      
+      {/* Video Overlay */}
+      <video ref={overlayRef} src={config.videoSrc} loop muted playsInline />
+    </div>
+  );
+};
+```
+
+---
+
+### 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
@@ -216,8 +261,15 @@ TapTapp AR uses a proprietary **Moonshot Vision Codec** that is significantly mo
 
 ---
 
-## 📄 License & Credits
+## 📄 License & Recognition
+
+**Taptapp AR** is created and maintained by **Sergio Lazaro**.
+
+This project is licensed under the **GPL-3.0 License**.
+This ensures that the project remains open and free, and that authorship is properly recognized. No "closed-source" usage is allowed without a commercial agreement.
+
+Commercial licenses are available for proprietary applications. Please contact the author for details.
 
-MIT © [srsergiolazaro](https://github.com/srsergiolazaro)
+### Acknowledgements
+This project evolved from the incredible work of [MindAR](https://github.com/hiukim/mind-ar-js). While the codebase has been extensively rewritten and optimized for performance, we gratefully acknowledge the foundation laid by the original authors.
 
-Based on the core research of MindAR, but completely re-written for high-performance binary processing and JS-only execution.

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/react/TaptappAR.d.ts

@@ -0,0 +1,9 @@
+import React from "react";
+import type { PropsConfig } from "./types.js";
+export interface TaptappARProps {
+    config: PropsConfig;
+    className?: string;
+    showScanningOverlay?: boolean;
+    showErrorOverlay?: boolean;
+}
+export declare const TaptappAR: React.FC<TaptappARProps>;

package/dist/react/TaptappAR.js

@@ -0,0 +1,97 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { useAR } from "./use-ar.js";
+export const TaptappAR = ({ config, className = "", showScanningOverlay = true, showErrorOverlay = true }) => {
+    const { containerRef, overlayRef, status, toggleVideo } = useAR(config);
+    // Simple heuristic to determine if it's a video or image
+    // based on the presence of videoSrc and common extensions
+    const isVideo = useMemo(() => {
+        if (!config.videoSrc)
+            return false;
+        const videoExtensions = ['.mp4', '.webm', '.ogg', '.mov'];
+        const url = config.videoSrc.toLowerCase().split('?')[0];
+        return videoExtensions.some(ext => url.endsWith(ext)) || config.videoSrc.includes('video');
+    }, [config.videoSrc]);
+    return (_jsxs("div", { className: `taptapp-ar-wrapper ${className} ${status}`, style: { position: 'relative', width: '100%', height: '100%', overflow: 'hidden' }, children: [showScanningOverlay && status === "scanning" && (_jsx("div", { className: "taptapp-ar-overlay taptapp-ar-scanning", children: _jsxs("div", { className: "scanning-content", children: [_jsxs("div", { className: "scanning-frame", children: [_jsx("img", { className: "target-preview", src: config.targetImageSrc, alt: "Target", crossOrigin: "anonymous" }), _jsx("div", { className: "scanning-line" })] }), _jsx("p", { className: "scanning-text", children: "Apunta a la imagen para comenzar" })] }) })), showErrorOverlay && status === "error" && (_jsx("div", { className: "taptapp-ar-overlay taptapp-ar-error", children: _jsxs("div", { className: "error-content", children: [_jsx("span", { className: "error-icon", children: "\u26A0\uFE0F" }), _jsx("p", { className: "error-title", children: "No se pudo iniciar AR" }), _jsx("p", { className: "error-text", children: "Verifica los permisos de c\u00E1mara" }), _jsx("button", { className: "retry-btn", onClick: () => window.location.reload(), children: "Reintentar" })] }) })), _jsx("div", { ref: containerRef, className: "taptapp-ar-container", onClick: toggleVideo, style: { width: '100%', height: '100%' }, children: isVideo ? (_jsx("video", { ref: overlayRef, className: "taptapp-ar-overlay-element", src: config.videoSrc, preload: "auto", loop: true, playsInline: true, muted: true, crossOrigin: "anonymous" })) : (_jsx("img", { ref: overlayRef, className: "taptapp-ar-overlay-element", src: config.videoSrc || config.targetImageSrc, crossOrigin: "anonymous", alt: "AR Overlay" })) }), _jsx("style", { children: `
+                .taptapp-ar-wrapper {
+                    background: #000;
+                    color: white;
+                    font-family: system-ui, -apple-system, sans-serif;
+                }
+                .taptapp-ar-overlay {
+                    position: absolute;
+                    top: 0;
+                    left: 0;
+                    right: 0;
+                    bottom: 0;
+                    z-index: 20;
+                    display: flex;
+                    align-items: center;
+                    justify-content: center;
+                    background: rgba(0,0,0,0.7);
+                    backdrop-filter: blur(4px);
+                    transition: opacity 0.3s ease;
+                }
+                .scanning-content, .error-content {
+                    text-align: center;
+                    display: flex;
+                    flex-direction: column;
+                    align-items: center;
+                    padding: 20px;
+                }
+                .scanning-frame {
+                    position: relative;
+                    width: 200px;
+                    height: 200px;
+                    border: 2px solid rgba(255,255,255,0.3);
+                    border-radius: 20px;
+                    overflow: hidden;
+                    margin-bottom: 20px;
+                }
+                .target-preview {
+                    width: 100%;
+                    height: 100%;
+                    object-fit: cover;
+                    opacity: 0.6;
+                }
+                .scanning-line {
+                    position: absolute;
+                    top: 0;
+                    left: 0;
+                    width: 100%;
+                    height: 2px;
+                    background: #00e5ff;
+                    box-shadow: 0 0 15px #00e5ff;
+                    animation: scan 2s linear infinite;
+                }
+                @keyframes scan {
+                    0% { top: 0; }
+                    50% { top: 100%; }
+                    100% { top: 0; }
+                }
+                .scanning-text {
+                    font-size: 1.1rem;
+                    font-weight: 500;
+                    letter-spacing: 0.5px;
+                }
+                .error-icon { font-size: 3rem; margin-bottom: 10px; }
+                .error-title { font-size: 1.2rem; font-weight: bold; margin: 0; }
+                .error-text { opacity: 0.8; margin: 5px 0 20px; }
+                .retry-btn {
+                    padding: 10px 25px;
+                    border-radius: 30px;
+                    border: none;
+                    background: #fff;
+                    color: #000;
+                    font-weight: 600;
+                    cursor: pointer;
+                    transition: transform 0.2s;
+                }
+                .retry-btn:active { transform: scale(0.95); }
+                .taptapp-ar-overlay-element {
+                    display: block;
+                    width: 100%;
+                    height: auto;
+                }
+            ` })] }));
+};

package/dist/react/use-ar.d.ts

@@ -0,0 +1,10 @@
+import type { PropsConfig } from "./types.js";
+export type ARStatus = "scanning" | "tracking" | "error";
+export interface UseARReturn {
+    containerRef: React.RefObject<HTMLDivElement>;
+    overlayRef: React.RefObject<HTMLVideoElement | HTMLImageElement>;
+    status: ARStatus;
+    isPlaying: boolean;
+    toggleVideo: () => Promise<void>;
+}
+export declare const useAR: (config: PropsConfig) => UseARReturn;

package/dist/react/use-ar.js

@@ -0,0 +1,94 @@
+import { useEffect, useRef, useState, useCallback } from "react";
+export const useAR = (config) => {
+    const containerRef = useRef(null);
+    const overlayRef = useRef(null);
+    const [status, setStatus] = useState("scanning");
+    const [isPlaying, setIsPlaying] = useState(false);
+    const arInstanceRef = useRef(null);
+    const toggleVideo = useCallback(async () => {
+        const overlay = overlayRef.current;
+        if (!(overlay instanceof HTMLVideoElement))
+            return;
+        try {
+            if (overlay.paused) {
+                await overlay.play();
+                setIsPlaying(true);
+            }
+            else {
+                overlay.pause();
+                setIsPlaying(false);
+            }
+        }
+        catch (err) {
+            console.error("Error toggling video:", err);
+        }
+    }, []);
+    useEffect(() => {
+        if (typeof window === "undefined" || !containerRef.current || !overlayRef.current)
+            return;
+        let isMounted = true;
+        const initAR = async () => {
+            try {
+                // Safe hybrid import for SSR + Speed
+                const { SimpleAR } = await import("../compiler/simple-ar.js");
+                if (!isMounted)
+                    return;
+                const instance = new SimpleAR({
+                    container: containerRef.current,
+                    targetSrc: config.targetTaarSrc,
+                    overlay: overlayRef.current,
+                    scale: config.scale,
+                    onFound: async ({ targetIndex }) => {
+                        console.log(`🎯 Target ${targetIndex} detected!`);
+                        if (!isMounted)
+                            return;
+                        setStatus("tracking");
+                        const overlay = overlayRef.current;
+                        if (overlay instanceof HTMLVideoElement) {
+                            try {
+                                await overlay.play();
+                                setIsPlaying(true);
+                            }
+                            catch (err) {
+                                console.warn("Auto-play blocked:", err);
+                            }
+                        }
+                    },
+                    onLost: ({ targetIndex }) => {
+                        console.log(`👋 Target ${targetIndex} lost`);
+                        if (!isMounted)
+                            return;
+                        setStatus("scanning");
+                        const overlay = overlayRef.current;
+                        if (overlay instanceof HTMLVideoElement) {
+                            overlay.pause();
+                            setIsPlaying(false);
+                        }
+                    }
+                });
+                arInstanceRef.current = instance;
+                await instance.start();
+                if (isMounted)
+                    setStatus("scanning");
+            }
+            catch (err) {
+                console.error("Failed to initialize AR:", err);
+                if (isMounted)
+                    setStatus("error");
+            }
+        };
+        initAR();
+        return () => {
+            isMounted = false;
+            arInstanceRef.current?.stop();
+            arInstanceRef.current = null;
+        };
+    }, [config.targetTaarSrc, config.scale]);
+    return {
+        containerRef,
+        overlayRef,
+        status,
+        isPlaying,
+        toggleVideo
+    };
+};

package/package.json

@@ -1,6 +1,8 @@
 {
     "name": "@srsergio/taptapp-ar",
-    "version": "1.0.53",
+    "version": "1.0.55",
+    "author": "Sergio Lazaro <srsergiolazaro@gmail.com>",
+    "license": "GPL-3.0",
     "description": "Ultra-fast, lightweight Augmented Reality Image Tracking SDK for the web. Features an optimized offline compiler, React components, and compatibility with Three.js/A-Frame. No heavy ML frameworks required.",
     "keywords": [
         "web-ar",

package/src/index.ts

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

package/src/react/TaptappAR.tsx

@@ -0,0 +1,176 @@
+import React, { useMemo } from "react";
+import { useAR } from "./use-ar.js";
+import type { PropsConfig } from "./types.js";
+
+export interface TaptappARProps {
+    config: PropsConfig;
+    className?: string;
+    showScanningOverlay?: boolean;
+    showErrorOverlay?: boolean;
+}
+
+export const TaptappAR: React.FC<TaptappARProps> = ({
+    config,
+    className = "",
+    showScanningOverlay = true,
+    showErrorOverlay = true
+}) => {
+    const { containerRef, overlayRef, status, toggleVideo } = useAR(config);
+
+    // Simple heuristic to determine if it's a video or image
+    // based on the presence of videoSrc and common extensions
+    const isVideo = useMemo(() => {
+        if (!config.videoSrc) return false;
+        const videoExtensions = ['.mp4', '.webm', '.ogg', '.mov'];
+        const url = config.videoSrc.toLowerCase().split('?')[0];
+        return videoExtensions.some(ext => url.endsWith(ext)) || config.videoSrc.includes('video');
+    }, [config.videoSrc]);
+
+    return (
+        <div className={`taptapp-ar-wrapper ${className} ${status}`} style={{ position: 'relative', width: '100%', height: '100%', overflow: 'hidden' }}>
+            {/* Scanning Overlay */}
+            {showScanningOverlay && status === "scanning" && (
+                <div className="taptapp-ar-overlay taptapp-ar-scanning">
+                    <div className="scanning-content">
+                        <div className="scanning-frame">
+                            <img
+                                className="target-preview"
+                                src={config.targetImageSrc}
+                                alt="Target"
+                                crossOrigin="anonymous"
+                            />
+                            <div className="scanning-line"></div>
+                        </div>
+                        <p className="scanning-text">Apunta a la imagen para comenzar</p>
+                    </div>
+                </div>
+            )}
+
+            {/* Error Overlay */}
+            {showErrorOverlay && status === "error" && (
+                <div className="taptapp-ar-overlay taptapp-ar-error">
+                    <div className="error-content">
+                        <span className="error-icon">⚠️</span>
+                        <p className="error-title">No se pudo iniciar AR</p>
+                        <p className="error-text">Verifica los permisos de cámara</p>
+                        <button className="retry-btn" onClick={() => window.location.reload()}>
+                            Reintentar
+                        </button>
+                    </div>
+                </div>
+            )}
+
+            {/* AR Container */}
+            <div
+                ref={containerRef}
+                className="taptapp-ar-container"
+                onClick={toggleVideo}
+                style={{ width: '100%', height: '100%' }}
+            >
+                {isVideo ? (
+                    <video
+                        ref={overlayRef as React.RefObject<HTMLVideoElement>}
+                        className="taptapp-ar-overlay-element"
+                        src={config.videoSrc}
+                        preload="auto"
+                        loop
+                        playsInline
+                        muted
+                        crossOrigin="anonymous"
+                    />
+                ) : (
+                    <img
+                        ref={overlayRef as React.RefObject<HTMLImageElement>}
+                        className="taptapp-ar-overlay-element"
+                        src={config.videoSrc || config.targetImageSrc}
+                        crossOrigin="anonymous"
+                        alt="AR Overlay"
+                    />
+                )}
+            </div>
+
+            <style>{`
+                .taptapp-ar-wrapper {
+                    background: #000;
+                    color: white;
+                    font-family: system-ui, -apple-system, sans-serif;
+                }
+                .taptapp-ar-overlay {
+                    position: absolute;
+                    top: 0;
+                    left: 0;
+                    right: 0;
+                    bottom: 0;
+                    z-index: 20;
+                    display: flex;
+                    align-items: center;
+                    justify-content: center;
+                    background: rgba(0,0,0,0.7);
+                    backdrop-filter: blur(4px);
+                    transition: opacity 0.3s ease;
+                }
+                .scanning-content, .error-content {
+                    text-align: center;
+                    display: flex;
+                    flex-direction: column;
+                    align-items: center;
+                    padding: 20px;
+                }
+                .scanning-frame {
+                    position: relative;
+                    width: 200px;
+                    height: 200px;
+                    border: 2px solid rgba(255,255,255,0.3);
+                    border-radius: 20px;
+                    overflow: hidden;
+                    margin-bottom: 20px;
+                }
+                .target-preview {
+                    width: 100%;
+                    height: 100%;
+                    object-fit: cover;
+                    opacity: 0.6;
+                }
+                .scanning-line {
+                    position: absolute;
+                    top: 0;
+                    left: 0;
+                    width: 100%;
+                    height: 2px;
+                    background: #00e5ff;
+                    box-shadow: 0 0 15px #00e5ff;
+                    animation: scan 2s linear infinite;
+                }
+                @keyframes scan {
+                    0% { top: 0; }
+                    50% { top: 100%; }
+                    100% { top: 0; }
+                }
+                .scanning-text {
+                    font-size: 1.1rem;
+                    font-weight: 500;
+                    letter-spacing: 0.5px;
+                }
+                .error-icon { font-size: 3rem; margin-bottom: 10px; }
+                .error-title { font-size: 1.2rem; font-weight: bold; margin: 0; }
+                .error-text { opacity: 0.8; margin: 5px 0 20px; }
+                .retry-btn {
+                    padding: 10px 25px;
+                    border-radius: 30px;
+                    border: none;
+                    background: #fff;
+                    color: #000;
+                    font-weight: 600;
+                    cursor: pointer;
+                    transition: transform 0.2s;
+                }
+                .retry-btn:active { transform: scale(0.95); }
+                .taptapp-ar-overlay-element {
+                    display: block;
+                    width: 100%;
+                    height: auto;
+                }
+            `}</style>
+        </div>
+    );
+};

package/src/react/use-ar.ts

@@ -0,0 +1,109 @@
+import { useEffect, useRef, useState, useCallback } from "react";
+import type { PropsConfig } from "./types.js";
+import type { SimpleAR as SimpleARType } from "../compiler/simple-ar.js";
+
+export type ARStatus = "scanning" | "tracking" | "error";
+
+export interface UseARReturn {
+    containerRef: React.RefObject<HTMLDivElement>;
+    overlayRef: React.RefObject<HTMLVideoElement | HTMLImageElement>;
+    status: ARStatus;
+    isPlaying: boolean;
+    toggleVideo: () => Promise<void>;
+}
+
+export const useAR = (config: PropsConfig): UseARReturn => {
+    const containerRef = useRef<HTMLDivElement>(null);
+    const overlayRef = useRef<HTMLVideoElement | HTMLImageElement>(null);
+    const [status, setStatus] = useState<ARStatus>("scanning");
+    const [isPlaying, setIsPlaying] = useState(false);
+    const arInstanceRef = useRef<SimpleARType | null>(null);
+
+    const toggleVideo = useCallback(async () => {
+        const overlay = overlayRef.current;
+        if (!(overlay instanceof HTMLVideoElement)) return;
+
+        try {
+            if (overlay.paused) {
+                await overlay.play();
+                setIsPlaying(true);
+            } else {
+                overlay.pause();
+                setIsPlaying(false);
+            }
+        } catch (err) {
+            console.error("Error toggling video:", err);
+        }
+    }, []);
+
+    useEffect(() => {
+        if (typeof window === "undefined" || !containerRef.current || !overlayRef.current) return;
+
+        let isMounted = true;
+
+        const initAR = async () => {
+            try {
+                // Safe hybrid import for SSR + Speed
+                const { SimpleAR } = await import("../compiler/simple-ar.js");
+                if (!isMounted) return;
+
+                const instance = new SimpleAR({
+                    container: containerRef.current!,
+                    targetSrc: config.targetTaarSrc,
+                    overlay: overlayRef.current!,
+                    scale: config.scale,
+                    onFound: async ({ targetIndex }) => {
+                        console.log(`🎯 Target ${targetIndex} detected!`);
+                        if (!isMounted) return;
+                        setStatus("tracking");
+
+                        const overlay = overlayRef.current;
+                        if (overlay instanceof HTMLVideoElement) {
+                            try {
+                                await overlay.play();
+                                setIsPlaying(true);
+                            } catch (err) {
+                                console.warn("Auto-play blocked:", err);
+                            }
+                        }
+                    },
+                    onLost: ({ targetIndex }) => {
+                        console.log(`👋 Target ${targetIndex} lost`);
+                        if (!isMounted) return;
+                        setStatus("scanning");
+
+                        const overlay = overlayRef.current;
+                        if (overlay instanceof HTMLVideoElement) {
+                            overlay.pause();
+                            setIsPlaying(false);
+                        }
+                    }
+                });
+
+                arInstanceRef.current = instance;
+                await instance.start();
+
+                if (isMounted) setStatus("scanning");
+            } catch (err) {
+                console.error("Failed to initialize AR:", err);
+                if (isMounted) setStatus("error");
+            }
+        };
+
+        initAR();
+
+        return () => {
+            isMounted = false;
+            arInstanceRef.current?.stop();
+            arInstanceRef.current = null;
+        };
+    }, [config.targetTaarSrc, config.scale]);
+
+    return {
+        containerRef,
+        overlayRef,
+        status,
+        isPlaying,
+        toggleVideo
+    };
+};