@mostajs/face 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Dr Hamid MADANI <drmdh@msn.com>
+
+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

@@ -0,0 +1,73 @@
+# @mostajs/face
+
+> Reusable face recognition module — detection, descriptor extraction, 1:N matching.
+
+[![npm version](https://img.shields.io/npm/v/@mostajs/face.svg)](https://www.npmjs.com/package/@mostajs/face)
+[![license](https://img.shields.io/npm/l/@mostajs/face.svg)](LICENSE)
+
+Part of the [@mosta suite](https://mostajs.dev).
+
+---
+
+## Installation
+
+```bash
+npm install @mostajs/face
+```
+
+## Quick Start
+
+### 1. Load models and detect faces
+
+```typescript
+import { loadModels, detectFace, extractDescriptor } from '@mostajs/face'
+
+await loadModels('/models')  // path to face-api.js model files
+
+const detection = await detectFace(imageElement)
+const descriptor = await extractDescriptor(imageElement)
+```
+
+### 2. Compare faces
+
+```typescript
+import { compareFaces, findMatch } from '@mostajs/face'
+
+const distance = compareFaces(descriptor1, descriptor2)
+
+const match = findMatch(unknownDescriptor, knownFaces, 0.6)
+if (match) {
+  console.log('Matched:', match.label, 'distance:', match.distance)
+}
+```
+
+### 3. React hooks
+
+```tsx
+import { useCamera } from '@mostajs/face/hooks/useCamera'
+import { useFaceDetection } from '@mostajs/face/hooks/useFaceDetection'
+
+function FaceCapture() {
+  const { videoRef, start, stop } = useCamera()
+  const { detection, descriptor } = useFaceDetection(videoRef)
+  // ...
+}
+```
+
+## API Reference
+
+| Export | Description |
+|--------|-------------|
+| `loadModels(path)` | Load face-api.js models |
+| `detectFace(input)` | Detect single face with landmarks |
+| `detectAllFaces(input)` | Detect all faces |
+| `extractDescriptor(input)` | Extract 128-dim face descriptor |
+| `compareFaces(d1, d2)` | Euclidean distance between descriptors |
+| `findMatch(descriptor, known, threshold)` | Find best match |
+| `findAllMatches(descriptor, known, threshold)` | Find all matches |
+| `useCamera()` | Camera management hook |
+| `useFaceDetection()` | Continuous detection hook |
+
+## License
+
+MIT — © 2025 Dr Hamid MADANI <drmdh@msn.com>

package/dist/hooks/useCamera.d.ts

@@ -0,0 +1,17 @@
+export type CameraStatus = 'idle' | 'requesting' | 'active' | 'denied' | 'error';
+interface UseCameraOptions {
+    facingMode?: 'user' | 'environment';
+    width?: number;
+    height?: number;
+    autoStart?: boolean;
+}
+export declare function useCamera(options?: UseCameraOptions): {
+    videoRef: import("react").RefObject<HTMLVideoElement | null>;
+    stream: MediaStream | null;
+    status: CameraStatus;
+    error: string | null;
+    start: () => Promise<void>;
+    stop: () => void;
+    switchCamera: () => Promise<void>;
+};
+export {};

package/dist/hooks/useCamera.js

@@ -0,0 +1,78 @@
+"use strict";
+// @mosta/face — useCamera hook
+// Author: Dr Hamid MADANI drmdh@msn.com
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useCamera = useCamera;
+const react_1 = require("react");
+function useCamera(options) {
+    const { facingMode = 'user', width = 640, height = 480, autoStart = false } = options || {};
+    const videoRef = (0, react_1.useRef)(null);
+    const [stream, setStream] = (0, react_1.useState)(null);
+    const [status, setStatus] = (0, react_1.useState)('idle');
+    const [error, setError] = (0, react_1.useState)(null);
+    const start = (0, react_1.useCallback)(async () => {
+        try {
+            setStatus('requesting');
+            setError(null);
+            const mediaStream = await navigator.mediaDevices.getUserMedia({
+                video: { facingMode, width: { ideal: width }, height: { ideal: height } },
+            });
+            if (videoRef.current) {
+                videoRef.current.srcObject = mediaStream;
+                await videoRef.current.play();
+            }
+            setStream(mediaStream);
+            setStatus('active');
+        }
+        catch (err) {
+            if (err.name === 'NotAllowedError') {
+                setStatus('denied');
+                setError('Camera permission denied');
+            }
+            else {
+                setStatus('error');
+                setError(err.message || 'Camera error');
+            }
+        }
+    }, [facingMode, width, height]);
+    const stop = (0, react_1.useCallback)(() => {
+        if (stream) {
+            stream.getTracks().forEach((t) => t.stop());
+            setStream(null);
+        }
+        if (videoRef.current) {
+            videoRef.current.srcObject = null;
+        }
+        setStatus('idle');
+    }, [stream]);
+    const switchCamera = (0, react_1.useCallback)(async () => {
+        stop();
+        // Toggle facing mode
+        const newMode = facingMode === 'user' ? 'environment' : 'user';
+        try {
+            const mediaStream = await navigator.mediaDevices.getUserMedia({
+                video: { facingMode: newMode, width: { ideal: width }, height: { ideal: height } },
+            });
+            if (videoRef.current) {
+                videoRef.current.srcObject = mediaStream;
+                await videoRef.current.play();
+            }
+            setStream(mediaStream);
+            setStatus('active');
+        }
+        catch (err) {
+            setStatus('error');
+            setError(err.message);
+        }
+    }, [stop, facingMode, width, height]);
+    (0, react_1.useEffect)(() => {
+        if (autoStart)
+            start();
+        return () => {
+            // Cleanup on unmount
+            stream?.getTracks().forEach((t) => t.stop());
+        };
+    }, []); // eslint-disable-line react-hooks/exhaustive-deps
+    return { videoRef, stream, status, error, start, stop, switchCamera };
+}

package/dist/hooks/useFaceDetection.d.ts

@@ -0,0 +1,21 @@
+import type { MostaFaceConfig } from '../types';
+export type DetectionStatus = 'loading' | 'detecting' | 'detected' | 'noFace';
+interface UseFaceDetectionOptions {
+    /** Interval between detections in ms (default: 300) */
+    interval?: number;
+    /** Auto-start detection (default: true) */
+    autoStart?: boolean;
+    /** Also extract descriptor on each frame (default: false) */
+    extractDescriptor?: boolean;
+    /** Face-api config */
+    config?: MostaFaceConfig;
+}
+export declare function useFaceDetection(videoRef: React.RefObject<HTMLVideoElement | null>, options?: UseFaceDetectionOptions): {
+    detection: any;
+    descriptor: Float32Array<ArrayBufferLike> | null;
+    status: DetectionStatus;
+    modelsLoaded: boolean;
+    stop: () => void;
+    start: () => Promise<void>;
+};
+export {};

package/dist/hooks/useFaceDetection.js

@@ -0,0 +1,97 @@
+"use strict";
+// @mosta/face — useFaceDetection hook
+// Author: Dr Hamid MADANI drmdh@msn.com
+'use client';
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useFaceDetection = useFaceDetection;
+const react_1 = require("react");
+function useFaceDetection(videoRef, options) {
+    const { interval = 300, autoStart = true, extractDescriptor: doExtract = false, config } = options || {};
+    const [detection, setDetection] = (0, react_1.useState)(null);
+    const [descriptor, setDescriptor] = (0, react_1.useState)(null);
+    const [status, setStatus] = (0, react_1.useState)('loading');
+    const [modelsLoaded, setModelsLoaded] = (0, react_1.useState)(false);
+    const running = (0, react_1.useRef)(false);
+    const timerRef = (0, react_1.useRef)(null);
+    const loadAndStart = (0, react_1.useCallback)(async () => {
+        const faceApi = await Promise.resolve().then(() => __importStar(require('../lib/face-api')));
+        await faceApi.loadModels(config);
+        setModelsLoaded(true);
+        setStatus('detecting');
+        running.current = true;
+        const detect = async () => {
+            if (!running.current || !videoRef.current)
+                return;
+            const video = videoRef.current;
+            if (video.readyState < 2) {
+                timerRef.current = setTimeout(detect, interval);
+                return;
+            }
+            const det = await faceApi.detectFace(video, config);
+            setDetection(det);
+            if (det) {
+                setStatus('detected');
+                if (doExtract) {
+                    const desc = await faceApi.extractDescriptor(video, config);
+                    setDescriptor(desc);
+                }
+            }
+            else {
+                setStatus('noFace');
+                setDescriptor(null);
+            }
+            if (running.current) {
+                timerRef.current = setTimeout(detect, interval);
+            }
+        };
+        detect();
+    }, [videoRef, interval, doExtract, config]);
+    (0, react_1.useEffect)(() => {
+        if (autoStart)
+            loadAndStart();
+        return () => {
+            running.current = false;
+            if (timerRef.current)
+                clearTimeout(timerRef.current);
+        };
+    }, [autoStart, loadAndStart]);
+    const stop = (0, react_1.useCallback)(() => {
+        running.current = false;
+        if (timerRef.current)
+            clearTimeout(timerRef.current);
+    }, []);
+    return { detection, descriptor, status, modelsLoaded, stop, start: loadAndStart };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { loadModels, isLoaded, detectFace, detectAllFaces, extractDescriptor } from './lib/face-api';
+export { compareFaces, findMatch, findAllMatches } from './lib/face-matcher';
+export { descriptorToArray, arrayToDescriptor, isValidDescriptor, drawDetection } from './lib/face-utils';
+export { useCamera } from './hooks/useCamera';
+export { useFaceDetection } from './hooks/useFaceDetection';
+export type { MostaFaceConfig, FaceDetectionResult, FaceMatchResult, FaceDescriptor } from './types';

package/dist/index.js

@@ -0,0 +1,28 @@
+"use strict";
+// @mosta/face — Barrel exports
+// Author: Dr Hamid MADANI drmdh@msn.com
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useFaceDetection = exports.useCamera = exports.drawDetection = exports.isValidDescriptor = exports.arrayToDescriptor = exports.descriptorToArray = exports.findAllMatches = exports.findMatch = exports.compareFaces = exports.extractDescriptor = exports.detectAllFaces = exports.detectFace = exports.isLoaded = exports.loadModels = void 0;
+// Core face-api service
+var face_api_1 = require("./lib/face-api");
+Object.defineProperty(exports, "loadModels", { enumerable: true, get: function () { return face_api_1.loadModels; } });
+Object.defineProperty(exports, "isLoaded", { enumerable: true, get: function () { return face_api_1.isLoaded; } });
+Object.defineProperty(exports, "detectFace", { enumerable: true, get: function () { return face_api_1.detectFace; } });
+Object.defineProperty(exports, "detectAllFaces", { enumerable: true, get: function () { return face_api_1.detectAllFaces; } });
+Object.defineProperty(exports, "extractDescriptor", { enumerable: true, get: function () { return face_api_1.extractDescriptor; } });
+// Matching
+var face_matcher_1 = require("./lib/face-matcher");
+Object.defineProperty(exports, "compareFaces", { enumerable: true, get: function () { return face_matcher_1.compareFaces; } });
+Object.defineProperty(exports, "findMatch", { enumerable: true, get: function () { return face_matcher_1.findMatch; } });
+Object.defineProperty(exports, "findAllMatches", { enumerable: true, get: function () { return face_matcher_1.findAllMatches; } });
+// Utils
+var face_utils_1 = require("./lib/face-utils");
+Object.defineProperty(exports, "descriptorToArray", { enumerable: true, get: function () { return face_utils_1.descriptorToArray; } });
+Object.defineProperty(exports, "arrayToDescriptor", { enumerable: true, get: function () { return face_utils_1.arrayToDescriptor; } });
+Object.defineProperty(exports, "isValidDescriptor", { enumerable: true, get: function () { return face_utils_1.isValidDescriptor; } });
+Object.defineProperty(exports, "drawDetection", { enumerable: true, get: function () { return face_utils_1.drawDetection; } });
+// Hooks
+var useCamera_1 = require("./hooks/useCamera");
+Object.defineProperty(exports, "useCamera", { enumerable: true, get: function () { return useCamera_1.useCamera; } });
+var useFaceDetection_1 = require("./hooks/useFaceDetection");
+Object.defineProperty(exports, "useFaceDetection", { enumerable: true, get: function () { return useFaceDetection_1.useFaceDetection; } });

package/dist/lib/face-api.d.ts

@@ -0,0 +1,23 @@
+import type { MostaFaceConfig } from '../types';
+/**
+ * Load the face-api.js library and 3 models (TinyFaceDetector, landmarks68, recognition).
+ */
+export declare function loadModels(config?: MostaFaceConfig): Promise<void>;
+/** Check if models are loaded */
+export declare function isLoaded(): boolean;
+/**
+ * Detect a single face with landmarks.
+ */
+export declare function detectFace(input: HTMLVideoElement | HTMLCanvasElement, config?: MostaFaceConfig): Promise<import("@vladmandic/face-api").WithFaceLandmarks<{
+    detection: import("@vladmandic/face-api").FaceDetection;
+}, import("@vladmandic/face-api").FaceLandmarks68> | null>;
+/**
+ * Detect all faces with landmarks.
+ */
+export declare function detectAllFaces(input: HTMLVideoElement | HTMLCanvasElement, config?: MostaFaceConfig): Promise<import("@vladmandic/face-api").WithFaceLandmarks<{
+    detection: import("@vladmandic/face-api").FaceDetection;
+}, import("@vladmandic/face-api").FaceLandmarks68>[]>;
+/**
+ * Extract the 128-dimensional face descriptor from a single face.
+ */
+export declare function extractDescriptor(input: HTMLVideoElement | HTMLCanvasElement, config?: MostaFaceConfig): Promise<Float32Array | null>;

package/dist/lib/face-api.js

@@ -0,0 +1,107 @@
+"use strict";
+// @mosta/face — Core face-api.js service (CLIENT-SIDE only)
+// Author: Dr Hamid MADANI drmdh@msn.com
+//
+// Usage: const faceApi = await import('@mosta/face') — always use dynamic import in useEffect
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadModels = loadModels;
+exports.isLoaded = isLoaded;
+exports.detectFace = detectFace;
+exports.detectAllFaces = detectAllFaces;
+exports.extractDescriptor = extractDescriptor;
+let fapi = null;
+let modelsLoaded = false;
+/**
+ * Load the face-api.js library and 3 models (TinyFaceDetector, landmarks68, recognition).
+ */
+async function loadModels(config) {
+    if (modelsLoaded)
+        return;
+    fapi = await Promise.resolve().then(() => __importStar(require('@vladmandic/face-api')));
+    const modelUrl = config?.modelsPath ?? '/models/face-api';
+    await Promise.all([
+        fapi.nets.tinyFaceDetector.loadFromUri(modelUrl),
+        fapi.nets.faceLandmark68Net.loadFromUri(modelUrl),
+        fapi.nets.faceRecognitionNet.loadFromUri(modelUrl),
+    ]);
+    modelsLoaded = true;
+}
+/** Check if models are loaded */
+function isLoaded() {
+    return modelsLoaded;
+}
+/**
+ * Detect a single face with landmarks.
+ */
+async function detectFace(input, config) {
+    if (!fapi)
+        throw new Error('face-api not loaded — call loadModels() first');
+    const detection = await fapi
+        .detectSingleFace(input, new fapi.TinyFaceDetectorOptions({
+        inputSize: config?.inputSize ?? 320,
+        scoreThreshold: config?.scoreThreshold ?? 0.5,
+    }))
+        .withFaceLandmarks();
+    return detection || null;
+}
+/**
+ * Detect all faces with landmarks.
+ */
+async function detectAllFaces(input, config) {
+    if (!fapi)
+        throw new Error('face-api not loaded — call loadModels() first');
+    return fapi
+        .detectAllFaces(input, new fapi.TinyFaceDetectorOptions({
+        inputSize: config?.inputSize ?? 320,
+        scoreThreshold: config?.scoreThreshold ?? 0.5,
+    }))
+        .withFaceLandmarks();
+}
+/**
+ * Extract the 128-dimensional face descriptor from a single face.
+ */
+async function extractDescriptor(input, config) {
+    if (!fapi)
+        throw new Error('face-api not loaded — call loadModels() first');
+    const result = await fapi
+        .detectSingleFace(input, new fapi.TinyFaceDetectorOptions({
+        inputSize: config?.inputSize ?? 320,
+        scoreThreshold: config?.scoreThreshold ?? 0.5,
+    }))
+        .withFaceLandmarks()
+        .withFaceDescriptor();
+    return result?.descriptor || null;
+}

package/dist/lib/face-matcher.d.ts

@@ -0,0 +1,18 @@
+import type { FaceDescriptor, FaceMatchResult } from '../types';
+/**
+ * Compute Euclidean distance between two 128-dim face descriptors.
+ */
+export declare function compareFaces(d1: FaceDescriptor, d2: FaceDescriptor): number;
+/**
+ * Find the best match among candidates.
+ * Returns null if no match is below the threshold.
+ */
+export declare function findMatch<T extends {
+    faceDescriptor: number[];
+}>(descriptor: FaceDescriptor, candidates: T[], threshold?: number): FaceMatchResult<T> | null;
+/**
+ * Find all matches below the threshold, sorted by distance.
+ */
+export declare function findAllMatches<T extends {
+    faceDescriptor: number[];
+}>(descriptor: FaceDescriptor, candidates: T[], threshold?: number): FaceMatchResult<T>[];

package/dist/lib/face-matcher.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compareFaces = compareFaces;
+exports.findMatch = findMatch;
+exports.findAllMatches = findAllMatches;
+/**
+ * Compute Euclidean distance between two 128-dim face descriptors.
+ */
+function compareFaces(d1, d2) {
+    const a = d1 instanceof Float32Array ? d1 : new Float32Array(d1);
+    const b = d2 instanceof Float32Array ? d2 : new Float32Array(d2);
+    if (a.length !== 128 || b.length !== 128) {
+        throw new Error('Descriptors must be 128 elements');
+    }
+    let sum = 0;
+    for (let i = 0; i < 128; i++) {
+        const diff = a[i] - b[i];
+        sum += diff * diff;
+    }
+    return Math.sqrt(sum);
+}
+/**
+ * Find the best match among candidates.
+ * Returns null if no match is below the threshold.
+ */
+function findMatch(descriptor, candidates, threshold = 0.6) {
+    let bestMatch = null;
+    let bestDistance = Infinity;
+    for (const candidate of candidates) {
+        if (!candidate.faceDescriptor || candidate.faceDescriptor.length !== 128)
+            continue;
+        const distance = compareFaces(descriptor, candidate.faceDescriptor);
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            bestMatch = candidate;
+        }
+    }
+    if (bestMatch && bestDistance < threshold) {
+        return { match: bestMatch, distance: bestDistance };
+    }
+    return null;
+}
+/**
+ * Find all matches below the threshold, sorted by distance.
+ */
+function findAllMatches(descriptor, candidates, threshold = 0.6) {
+    const results = [];
+    for (const candidate of candidates) {
+        if (!candidate.faceDescriptor || candidate.faceDescriptor.length !== 128)
+            continue;
+        const distance = compareFaces(descriptor, candidate.faceDescriptor);
+        if (distance < threshold) {
+            results.push({ match: candidate, distance });
+        }
+    }
+    return results.sort((a, b) => a.distance - b.distance);
+}

package/dist/lib/face-utils.d.ts

@@ -0,0 +1,20 @@
+/** Convert Float32Array descriptor to number[] for JSON/DB storage */
+export declare function descriptorToArray(descriptor: Float32Array): number[];
+/** Convert number[] back to Float32Array for comparison */
+export declare function arrayToDescriptor(arr: number[]): Float32Array;
+/** Validate that a descriptor is valid (128 elements) */
+export declare function isValidDescriptor(data: unknown): boolean;
+/**
+ * Draw a detection bounding box + score on a canvas overlay.
+ */
+export declare function drawDetection(canvas: HTMLCanvasElement, detection: {
+    detection: {
+        score: number;
+        box: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    };
+} | null, videoWidth: number, videoHeight: number): void;

package/dist/lib/face-utils.js

@@ -0,0 +1,45 @@
+"use strict";
+// @mosta/face — Utility functions
+// Author: Dr Hamid MADANI drmdh@msn.com
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.descriptorToArray = descriptorToArray;
+exports.arrayToDescriptor = arrayToDescriptor;
+exports.isValidDescriptor = isValidDescriptor;
+exports.drawDetection = drawDetection;
+/** Convert Float32Array descriptor to number[] for JSON/DB storage */
+function descriptorToArray(descriptor) {
+    return Array.from(descriptor);
+}
+/** Convert number[] back to Float32Array for comparison */
+function arrayToDescriptor(arr) {
+    return new Float32Array(arr);
+}
+/** Validate that a descriptor is valid (128 elements) */
+function isValidDescriptor(data) {
+    if (data instanceof Float32Array)
+        return data.length === 128;
+    if (Array.isArray(data))
+        return data.length === 128 && data.every((v) => typeof v === 'number');
+    return false;
+}
+/**
+ * Draw a detection bounding box + score on a canvas overlay.
+ */
+function drawDetection(canvas, detection, videoWidth, videoHeight) {
+    const ctx = canvas.getContext('2d');
+    if (!ctx)
+        return;
+    canvas.width = videoWidth;
+    canvas.height = videoHeight;
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+    if (!detection)
+        return;
+    const box = detection.detection.box;
+    ctx.strokeStyle = '#22c55e';
+    ctx.lineWidth = 3;
+    ctx.strokeRect(box.x, box.y, box.width, box.height);
+    const score = Math.round(detection.detection.score * 100);
+    ctx.fillStyle = '#22c55e';
+    ctx.font = 'bold 14px sans-serif';
+    ctx.fillText(`Visage ${score}%`, box.x, box.y - 6);
+}

package/dist/types/index.d.ts

@@ -0,0 +1,27 @@
+export interface MostaFaceConfig {
+    /** Path to face-api.js model files (default: '/models/face-api') */
+    modelsPath?: string;
+    /** Detection score threshold (default: 0.5) */
+    scoreThreshold?: number;
+    /** TinyFaceDetector input size (default: 320) */
+    inputSize?: number;
+    /** Face matching distance threshold (default: 0.6) */
+    matchThreshold?: number;
+}
+export interface FaceDetectionResult {
+    detection: {
+        score: number;
+        box: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    };
+    landmarks?: any;
+}
+export interface FaceMatchResult<T> {
+    match: T;
+    distance: number;
+}
+export type FaceDescriptor = Float32Array | number[];

package/dist/types/index.js

@@ -0,0 +1,4 @@
+"use strict";
+// @mosta/face — Types
+// Author: Dr Hamid MADANI drmdh@msn.com
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@mostajs/face",
+  "version": "1.0.0",
+  "description": "Reusable face recognition module — detection, descriptor extraction, 1:N matching",
+  "author": "Dr Hamid MADANI <drmdh@msn.com>",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./hooks/useCamera": {
+      "types": "./dist/hooks/useCamera.d.ts",
+      "import": "./dist/hooks/useCamera.js",
+      "require": "./dist/hooks/useCamera.js",
+      "default": "./dist/hooks/useCamera.js"
+    },
+    "./hooks/useFaceDetection": {
+      "types": "./dist/hooks/useFaceDetection.d.ts",
+      "import": "./dist/hooks/useFaceDetection.js",
+      "require": "./dist/hooks/useFaceDetection.js",
+      "default": "./dist/hooks/useFaceDetection.js"
+    }
+  },
+  "files": ["dist", "LICENSE", "README.md"],
+  "keywords": ["face-recognition", "face-detection", "face-api", "biometrics", "react", "mosta"],
+  "repository": { "type": "git", "url": "https://github.com/apolocine/mosta-face" },
+  "homepage": "https://mostajs.dev/packages/face",
+  "engines": { "node": ">=18.0.0" },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@vladmandic/face-api": "^1.7.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "typescript": "^5.6.0"
+  }
+}