@mostajs/face 1.0.0 → 1.2.0

package/README.md

@@ -1,11 +1,23 @@
 # @mostajs/face
 
-> Reusable face recognition module — detection, descriptor extraction, 1:N matching.
+> Reusable face recognition module — detection, descriptor extraction, 1:N matching, API route factories.
 
 [![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).
+Part of the [@mosta suite](https://mostajs.dev). **100% standalone** — zero dependency on `@mostajs/orm` or any other `@mostajs/*` package.
+
+---
+
+## Table des matieres
+
+1. [Installation](#installation)
+2. [Quick Start](#quick-start)
+3. [API Route Factories](#api-route-factories)
+4. [React Hooks](#react-hooks)
+5. [Integration complete dans une nouvelle app](#integration-complete)
+6. [API Reference](#api-reference)
+7. [Architecture](#architecture)
 
 ---
 
@@ -15,59 +27,411 @@ Part of the [@mosta suite](https://mostajs.dev).
 npm install @mostajs/face
 ```
 
+Copier les modeles face-api.js dans votre dossier `public/` :
+
+```bash
+mkdir -p public/models/face-api
+# Copier les fichiers .bin et .json depuis node_modules/@vladmandic/face-api/model/
+cp node_modules/@vladmandic/face-api/model/tiny_face_detector_model-* public/models/face-api/
+cp node_modules/@vladmandic/face-api/model/face_landmark_68_model-* public/models/face-api/
+cp node_modules/@vladmandic/face-api/model/face_recognition_model-* public/models/face-api/
+```
+
+---
+
 ## Quick Start
 
-### 1. Load models and detect faces
+### 1. Charger les modeles et detecter des visages
 
 ```typescript
 import { loadModels, detectFace, extractDescriptor } from '@mostajs/face'
 
-await loadModels('/models')  // path to face-api.js model files
+await loadModels('/models/face-api')
 
 const detection = await detectFace(imageElement)
-const descriptor = await extractDescriptor(imageElement)
+const descriptor = await extractDescriptor(imageElement) // Float32Array(128)
 ```
 
-### 2. Compare faces
+### 2. Comparer des visages
 
 ```typescript
 import { compareFaces, findMatch } from '@mostajs/face'
 
+// Distance euclidienne entre deux descripteurs
 const distance = compareFaces(descriptor1, descriptor2)
+console.log(distance < 0.6 ? 'Meme personne' : 'Personnes differentes')
 
-const match = findMatch(unknownDescriptor, knownFaces, 0.6)
+// Recherche 1:N parmi des candidats
+const candidates = [
+  { id: '1', faceDescriptor: [...], name: 'Alice' },
+  { id: '2', faceDescriptor: [...], name: 'Bob' },
+]
+const match = findMatch(unknownDescriptor, candidates, 0.6)
 if (match) {
-  console.log('Matched:', match.label, 'distance:', match.distance)
+  console.log('Match:', match.match.name, 'distance:', match.distance)
+}
+```
+
+---
+
+## API Route Factories
+
+Depuis la v1.1.0, le package fournit des factories pour creer des routes API (Next.js App Router ou tout framework supportant `Request`/`Response`).
+
+### POST /api/face/recognize
+
+Factory qui recoit un descripteur facial et cherche le meilleur match parmi vos candidats.
+
+```typescript
+// src/app/api/face/recognize/route.ts
+import { createRecognizeHandler } from '@mostajs/face/api/recognize.route'
+import { db } from '@/lib/db'
+
+export const { POST } = createRecognizeHandler({
+  // Fournir les candidats depuis votre base de donnees
+  getCandidates: async () => {
+    return db.query('SELECT id, name, photo, "faceDescriptor" FROM users WHERE "faceDescriptor" IS NOT NULL')
+  },
+
+  // Seuil de matching (defaut: 0.6)
+  getThreshold: async () => 0.55,
+
+  // Champs retournes dans la reponse (defaut: tous sauf faceDescriptor)
+  publicFields: ['name', 'photo', 'email'],
+
+  // Optionnel: verifier l'authentification
+  checkAuth: async (req) => {
+    const token = req.headers.get('Authorization')
+    if (!token) return Response.json({ error: 'Unauthorized' }, { status: 401 })
+    return null // OK
+  },
+
+  // Optionnel: desactiver la feature
+  isEnabled: async () => {
+    const settings = await getAppSettings()
+    return settings.faceRecognitionEnabled
+  },
+})
+```
+
+**Requete :**
+```json
+POST /api/face/recognize
+{ "faceDescriptor": [0.023, -0.114, 0.087, ...] }
+```
+
+**Reponse (match) :**
+```json
+{
+  "data": {
+    "match": true,
+    "distance": 0.312,
+    "candidate": { "id": "abc123", "name": "Alice", "photo": "/photos/alice.jpg" }
+  }
+}
+```
+
+**Reponse (pas de match) :**
+```json
+{
+  "data": { "match": false, "distance": 0.782 }
 }
 ```
 
-### 3. React hooks
+### POST /api/face/detect (placeholder)
+
+```typescript
+// src/app/api/face/detect/route.ts
+import { createDetectHandler } from '@mostajs/face/api/detect.route'
+
+export const { POST } = createDetectHandler({
+  checkAuth: async (req) => { /* ... */ return null },
+  isEnabled: async () => true,
+})
+```
+
+> La detection se fait cote client via face-api.js. Cette route sert de point d'entree pour le controle d'acces et un futur traitement serveur.
+
+---
+
+## React Hooks
+
+### useCamera
 
 ```tsx
 import { useCamera } from '@mostajs/face/hooks/useCamera'
+
+function CameraView() {
+  const { videoRef, streaming, start, stop, capture } = useCamera()
+
+  return (
+    <div>
+      <video ref={videoRef} autoPlay playsInline muted />
+      {!streaming
+        ? <button onClick={start}>Demarrer</button>
+        : <button onClick={() => capture(canvas)}>Capturer</button>
+      }
+    </div>
+  )
+}
+```
+
+### useFaceDetection
+
+```tsx
 import { useFaceDetection } from '@mostajs/face/hooks/useFaceDetection'
 
-function FaceCapture() {
-  const { videoRef, start, stop } = useCamera()
-  const { detection, descriptor } = useFaceDetection(videoRef)
-  // ...
+function LiveDetection({ videoRef }) {
+  const { faceDetected, detection, descriptor } = useFaceDetection(videoRef, {
+    scoreThreshold: 0.5,
+    inputSize: 320,
+  })
+
+  return <span>{faceDetected ? 'Visage detecte' : 'Aucun visage'}</span>
+}
+```
+
+---
+
+## Integration complete
+
+Exemple complet d'integration dans une nouvelle app Next.js.
+
+### Etape 1 — Installer
+
+```bash
+npm install @mostajs/face
+```
+
+### Etape 2 — Copier les modeles
+
+```bash
+mkdir -p public/models/face-api
+cp node_modules/@vladmandic/face-api/model/tiny_face_detector_model-* public/models/face-api/
+cp node_modules/@vladmandic/face-api/model/face_landmark_68_model-* public/models/face-api/
+cp node_modules/@vladmandic/face-api/model/face_recognition_model-* public/models/face-api/
+```
+
+### Etape 3 — Route API recognize
+
+```typescript
+// src/app/api/face/recognize/route.ts
+import { createRecognizeHandler } from '@mostajs/face/api/recognize.route'
+import prisma from '@/lib/prisma' // ou tout ORM
+
+export const { POST } = createRecognizeHandler({
+  getCandidates: async () => {
+    const users = await prisma.user.findMany({
+      where: { faceDescriptor: { not: null } },
+      select: { id: true, name: true, photo: true, faceDescriptor: true },
+    })
+    return users.map(u => ({
+      ...u,
+      faceDescriptor: u.faceDescriptor as number[],
+    }))
+  },
+  getThreshold: async () => 0.6,
+  publicFields: ['name', 'photo'],
+})
+```
+
+### Etape 4 — Composant React
+
+```tsx
+'use client'
+import { useState, useRef, useEffect, useCallback } from 'react'
+import { useCamera } from '@mostajs/face/hooks/useCamera'
+
+export default function FaceSearch() {
+  const { videoRef, streaming, start, stop } = useCamera()
+  const [result, setResult] = useState(null)
+  const faceApiRef = useRef(null)
+
+  useEffect(() => {
+    import('@mostajs/face').then(mod => {
+      mod.loadModels('/models/face-api')
+      faceApiRef.current = mod
+    })
+  }, [])
+
+  const recognize = useCallback(async () => {
+    if (!faceApiRef.current || !videoRef.current) return
+    const descriptor = await faceApiRef.current.extractDescriptor(videoRef.current)
+    if (!descriptor) { alert('Aucun visage'); return }
+
+    const res = await fetch('/api/face/recognize', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ faceDescriptor: Array.from(descriptor) }),
+    })
+    const json = await res.json()
+    setResult(json.data)
+  }, [videoRef])
+
+  return (
+    <div>
+      <video ref={videoRef} autoPlay playsInline muted />
+      {!streaming
+        ? <button onClick={start}>Camera</button>
+        : <button onClick={recognize}>Rechercher</button>
+      }
+      {result?.match && <p>Trouve: {result.candidate.name}</p>}
+    </div>
+  )
 }
 ```
 
+### Etape 5 — Verification locale
+
+```bash
+# Demarrer l'app
+npm run dev
+
+# Tester l'API
+curl -X POST http://localhost:3000/api/face/recognize \
+  -H 'Content-Type: application/json' \
+  -d '{"faceDescriptor": [0.1, 0.2, ...]}'
+```
+
+---
+
 ## API Reference
 
+### Core (client-side)
+
+| Export | Description |
+|--------|-------------|
+| `loadModels(path)` | Charger les modeles face-api.js |
+| `isLoaded()` | Verifier si les modeles sont charges |
+| `detectFace(input)` | Detecter un visage avec landmarks |
+| `detectAllFaces(input)` | Detecter tous les visages |
+| `extractDescriptor(input)` | Extraire un descripteur 128-dim |
+
+### Matching (client ou serveur)
+
+| Export | Description |
+|--------|-------------|
+| `compareFaces(d1, d2)` | Distance euclidienne entre 2 descripteurs |
+| `findMatch(descriptor, candidates, threshold)` | Meilleur match sous le seuil |
+| `findAllMatches(descriptor, candidates, threshold)` | Tous les matchs sous le seuil |
+
+### Utils
+
 | 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 |
+| `descriptorToArray(Float32Array)` | Convertir en `number[]` |
+| `arrayToDescriptor(number[])` | Convertir en `Float32Array` |
+| `isValidDescriptor(value)` | Verifier (128 nombres) |
+| `drawDetection(canvas, detection, w, h)` | Dessiner le cadre de detection |
+
+### Route Factories (serveur)
+
+| Export | Description |
+|--------|-------------|
+| `createRecognizeHandler(config)` | Factory POST recognize avec matching 1:N |
+| `createDetectHandler(config?)` | Factory POST detect (placeholder) |
+
+### React Hooks
+
+| Export | Description |
+|--------|-------------|
+| `useCamera()` | Gestion camera (start/stop/capture) |
+| `useFaceDetection(videoRef, config?)` | Detection continue en temps reel |
+
+### Types
+
+| Type | Description |
+|------|-------------|
+| `MostaFaceConfig` | Configuration (modelsPath, thresholds, inputSize) |
+| `FaceDetectionResult` | Resultat detection (score, box) |
+| `FaceMatchResult<T>` | Resultat matching (match, distance) |
+| `FaceDescriptor` | `Float32Array \| number[]` |
+| `FaceCandidate` | Interface candidat (id, faceDescriptor, ...) |
+| `RecognizeHandlerConfig` | Config de `createRecognizeHandler` |
+| `DetectHandlerConfig` | Config de `createDetectHandler` |
+
+---
+
+## Architecture
+
+```
+@mostajs/face (100% standalone)
+├── lib/
+│   ├── face-api.ts         # Chargement modeles, detection, extraction
+│   ├── face-matcher.ts     # Comparaison, findMatch, findAllMatches
+│   └── face-utils.ts       # Dessin, conversion descripteurs
+├── api/
+│   ├── recognize.route.ts  # Factory POST /api/face/recognize
+│   └── detect.route.ts     # Factory POST /api/face/detect
+├── hooks/
+│   ├── useCamera.ts        # Hook gestion camera
+│   └── useFaceDetection.ts # Hook detection temps reel
+├── types/
+│   └── index.ts            # Types exports
+└── index.ts                # Barrel exports
+
+Dependances:
+  @vladmandic/face-api  (seule dep runtime)
+  react >= 18           (peer dependency)
+
+Zero dependance sur: @mostajs/orm, @mostajs/auth, @mostajs/settings
+```
+
+### Pattern Factory
+
+Le meme pattern que `@mostajs/setup` : le package exporte des factories, l'app injecte ses dependances :
+
+```
+┌─────────────────────┐     inject callbacks      ┌──────────────────────┐
+│   @mostajs/face     │ ◄──────────────────────── │   Votre app          │
+│                     │                            │                      │
+│ createRecognizeHandler({                         │ getCandidates: () => │
+│   getCandidates,    │                            │   db.query(...)      │
+│   checkAuth,        │                            │ checkAuth: () =>     │
+│   getThreshold,     │                            │   verifyToken(...)   │
+│ })                  │                            │                      │
+└─────────────────────┘                            └──────────────────────┘
+```
+
+
+                                                                             
+  Résultat
+                                                                                    
+  Ce qui a été migré dans @mostajs/face v1.1.0
+                                                                                    
+  ┌────────────────────────┬─────────────────────────────────────────────────────┐
+  │        Fichier         │                     Description                     │
+  ├────────────────────────┼─────────────────────────────────────────────────────┤
+  │ api/recognize.route.ts │ Factory createRecognizeHandler() — matching 1:N     │
+  │                        │ avec callbacks injectés                             │
+  ├────────────────────────┼─────────────────────────────────────────────────────┤
+  │ api/detect.route.ts    │ Factory createDetectHandler() — placeholder avec    │
+  │                        │ auth/enable                                         │
+  ├────────────────────────┼─────────────────────────────────────────────────────┤
+  │ index.ts               │ +4 exports (2 factories + 2 types)                  │
+  ├────────────────────────┼─────────────────────────────────────────────────────┤
+  │ package.json           │ v1.1.0, subpath exports ./api/*, ./lib/*, ./types   │
+  ├────────────────────────┼─────────────────────────────────────────────────────┤
+  │ README.md              │ Tutoriel complet avec intégration nouvelle app      │
+  └────────────────────────┴─────────────────────────────────────────────────────┘
+
+  Routes app simplifiées
+
+  - src/app/api/face/recognize/route.ts : 101 lignes → 30 lignes (injection de
+  getCandidates, checkAuth, getThreshold, publicFields)
+  - src/app/api/face/detect/route.ts : 30 lignes → 15 lignes
+
+  Ce qui reste dans l'app (non migré)
+
+  - src/app/api/scan/route.ts — Scanning de tickets (QR, quotas, réentrée). Pas lié
+  à face, relève d'un futur @mostajs/ticketing
+  - src/components/clients/FaceDetector.tsx — Composant UI trop couplé (shadcn,
+  sonner, settings). Les hooks useCamera/useFaceDetection du package couvrent la
+  partie réutilisable
+
+
+---
 
 ## License
 
-MIT — © 2025 Dr Hamid MADANI <drmdh@msn.com>
+MIT — Dr Hamid MADANI <drmdh@msn.com>

package/dist/api/detect.route.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Configuration for the detect handler.
+ */
+export interface DetectHandlerConfig {
+    /** Check auth/permission — return null if OK, or a Response to deny */
+    checkAuth?: (req: Request) => Promise<Response | null>;
+    /** Check if face recognition is enabled (default: always true) */
+    isEnabled?: () => Promise<boolean>;
+}
+/**
+ * Factory for POST /api/face/detect
+ *
+ * Placeholder endpoint — face detection runs client-side via face-api.js.
+ * This route exists for permission gating and future server-side detection.
+ *
+ * @example
+ * ```ts
+ * import { createDetectHandler } from '@mostajs/face/api/detect.route'
+ * export const { POST } = createDetectHandler()
+ * ```
+ */
+export declare function createDetectHandler(config?: DetectHandlerConfig): {
+    POST: (req: Request) => Promise<Response>;
+};

package/dist/api/detect.route.js

@@ -0,0 +1,39 @@
+"use strict";
+// @mosta/face — Detect API route factory (placeholder)
+// Author: Dr Hamid MADANI drmdh@msn.com
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDetectHandler = createDetectHandler;
+/**
+ * Factory for POST /api/face/detect
+ *
+ * Placeholder endpoint — face detection runs client-side via face-api.js.
+ * This route exists for permission gating and future server-side detection.
+ *
+ * @example
+ * ```ts
+ * import { createDetectHandler } from '@mostajs/face/api/detect.route'
+ * export const { POST } = createDetectHandler()
+ * ```
+ */
+function createDetectHandler(config = {}) {
+    async function POST(req) {
+        if (config.isEnabled) {
+            const enabled = await config.isEnabled();
+            if (!enabled) {
+                return Response.json({ error: { code: 'FEATURE_DISABLED', message: 'Face recognition is disabled' } }, { status: 403 });
+            }
+        }
+        if (config.checkAuth) {
+            const denied = await config.checkAuth(req);
+            if (denied)
+                return denied;
+        }
+        return Response.json({
+            data: {
+                message: 'Face detection runs client-side. Use the FaceDetector component or useFaceDetection hook.',
+                hint: 'For recognition, send the descriptor to POST /api/face/recognize',
+            },
+        });
+    }
+    return { POST };
+}

package/dist/api/recognize.route.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Candidate shape: must have an id, faceDescriptor, and any extra fields.
+ */
+export interface FaceCandidate {
+    id: string;
+    faceDescriptor: number[];
+    [key: string]: unknown;
+}
+/**
+ * Configuration for the recognize handler.
+ */
+export interface RecognizeHandlerConfig {
+    /** Fetch all active candidates with a faceDescriptor from the database */
+    getCandidates: () => Promise<FaceCandidate[]>;
+    /** Check auth/permission — return null if OK, or a Response to deny */
+    checkAuth?: (req: Request) => Promise<Response | null>;
+    /** Get the matching distance threshold (default: 0.6) */
+    getThreshold?: () => Promise<number>;
+    /** Check if face recognition is enabled (default: always true) */
+    isEnabled?: () => Promise<boolean>;
+    /** Fields to return from the matched candidate (default: all except faceDescriptor) */
+    publicFields?: string[];
+}
+/**
+ * Factory for POST /api/face/recognize
+ *
+ * Receives a 128-float face descriptor, searches candidates, returns best match.
+ *
+ * @example
+ * ```ts
+ * // app route: src/app/api/face/recognize/route.ts
+ * import { createRecognizeHandler } from '@mostajs/face/api/recognize.route'
+ * import { clientRepo } from '@/dal/service'
+ *
+ * export const { POST } = createRecognizeHandler({
+ *   getCandidates: async () => {
+ *     const repo = await clientRepo()
+ *     return repo.findAll(
+ *       { faceDescriptor: { $exists: true, $not: { $size: 0 } }, status: 'active' },
+ *       { select: ['firstName', 'lastName', 'clientNumber', 'photo', 'faceDescriptor'] },
+ *     )
+ *   },
+ *   getThreshold: async () => 0.6,
+ * })
+ * ```
+ */
+export declare function createRecognizeHandler(config: RecognizeHandlerConfig): {
+    POST: (req: Request) => Promise<Response>;
+};

package/dist/api/recognize.route.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRecognizeHandler = createRecognizeHandler;
+// @mosta/face — Recognize API route factory
+// Author: Dr Hamid MADANI drmdh@msn.com
+const face_matcher_1 = require("../lib/face-matcher");
+/**
+ * Factory for POST /api/face/recognize
+ *
+ * Receives a 128-float face descriptor, searches candidates, returns best match.
+ *
+ * @example
+ * ```ts
+ * // app route: src/app/api/face/recognize/route.ts
+ * import { createRecognizeHandler } from '@mostajs/face/api/recognize.route'
+ * import { clientRepo } from '@/dal/service'
+ *
+ * export const { POST } = createRecognizeHandler({
+ *   getCandidates: async () => {
+ *     const repo = await clientRepo()
+ *     return repo.findAll(
+ *       { faceDescriptor: { $exists: true, $not: { $size: 0 } }, status: 'active' },
+ *       { select: ['firstName', 'lastName', 'clientNumber', 'photo', 'faceDescriptor'] },
+ *     )
+ *   },
+ *   getThreshold: async () => 0.6,
+ * })
+ * ```
+ */
+function createRecognizeHandler(config) {
+    async function POST(req) {
+        // Check if enabled
+        if (config.isEnabled) {
+            const enabled = await config.isEnabled();
+            if (!enabled) {
+                return Response.json({ error: { code: 'FEATURE_DISABLED', message: 'Face recognition is disabled' } }, { status: 403 });
+            }
+        }
+        // Check auth
+        if (config.checkAuth) {
+            const denied = await config.checkAuth(req);
+            if (denied)
+                return denied;
+        }
+        // Parse body
+        let body;
+        try {
+            body = await req.json();
+        }
+        catch {
+            return Response.json({ error: { code: 'VALIDATION_ERROR', message: 'Invalid JSON' } }, { status: 400 });
+        }
+        // Validate descriptor
+        const desc = body.faceDescriptor;
+        if (!Array.isArray(desc) ||
+            desc.length !== 128 ||
+            !desc.every((v) => typeof v === 'number')) {
+            return Response.json({ error: { code: 'VALIDATION_ERROR', message: 'faceDescriptor must be an array of 128 numbers' } }, { status: 400 });
+        }
+        // Get candidates
+        const candidates = await config.getCandidates();
+        if (candidates.length === 0) {
+            return Response.json({
+                data: { match: false, message: 'No candidates with face data' },
+            });
+        }
+        // Find match
+        const threshold = config.getThreshold ? await config.getThreshold() : 0.6;
+        const result = (0, face_matcher_1.findMatch)(desc, candidates, threshold);
+        if (result) {
+            // Strip faceDescriptor from response
+            const { faceDescriptor: _fd, ...publicData } = result.match;
+            const filtered = config.publicFields
+                ? Object.fromEntries(Object.entries(publicData).filter(([k]) => config.publicFields.includes(k) || k === 'id'))
+                : publicData;
+            return Response.json({
+                data: {
+                    match: true,
+                    distance: Math.round(result.distance * 1000) / 1000,
+                    candidate: filtered,
+                },
+            });
+        }
+        // No match — still report best distance for debugging
+        let bestDistance = null;
+        for (const c of candidates) {
+            if (!c.faceDescriptor || c.faceDescriptor.length !== 128)
+                continue;
+            let sum = 0;
+            for (let i = 0; i < 128; i++) {
+                const diff = desc[i] - c.faceDescriptor[i];
+                sum += diff * diff;
+            }
+            const d = Math.sqrt(sum);
+            if (bestDistance === null || d < bestDistance)
+                bestDistance = d;
+        }
+        return Response.json({
+            data: {
+                match: false,
+                distance: bestDistance !== null ? Math.round(bestDistance * 1000) / 1000 : null,
+            },
+        });
+    }
+    return { POST };
+}

package/dist/components/FaceDetector.d.ts

@@ -0,0 +1,27 @@
+export interface FaceDetectorProps {
+    /** Existing photo (base64) */
+    photo: string;
+    /** Callback when a photo is captured */
+    onCapture: (data: {
+        photo: string;
+        faceDescriptor: number[] | null;
+    }) => void;
+    /** Callback when photo is cleared */
+    onClear: () => void;
+    /** Verification mode: compare against existing descriptor */
+    verifyDescriptor?: number[];
+    /** Callback with verification result */
+    onVerifyResult?: (result: {
+        match: boolean;
+        distance: number;
+    } | null) => void;
+    /** Enable face detection (default: true) */
+    enabled?: boolean;
+    /** Match threshold (default: 0.6) */
+    threshold?: number;
+    /** Require face detected before capture (default: true) */
+    requireForCapture?: boolean;
+    /** Error callback instead of console.error */
+    onError?: (message: string) => void;
+}
+export default function FaceDetector({ photo, onCapture, onClear, verifyDescriptor, onVerifyResult, enabled, threshold, requireForCapture, onError, }: FaceDetectorProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/FaceDetector.js

@@ -0,0 +1,177 @@
+"use strict";
+// @mostajs/face — FaceDetector component
+// Author: Dr Hamid MADANI drmdh@msn.com
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = FaceDetector;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const face_api_1 = require("../lib/face-api");
+const face_matcher_1 = require("../lib/face-matcher");
+const face_utils_1 = require("../lib/face-utils");
+function FaceDetector({ photo, onCapture, onClear, verifyDescriptor, onVerifyResult, enabled = true, threshold = 0.6, requireForCapture = true, onError, }) {
+    const videoRef = (0, react_1.useRef)(null);
+    const canvasRef = (0, react_1.useRef)(null);
+    const overlayRef = (0, react_1.useRef)(null);
+    const animFrameRef = (0, react_1.useRef)(0);
+    const [streaming, setStreaming] = (0, react_1.useState)(false);
+    const [modelsReady, setModelsReady] = (0, react_1.useState)(false);
+    const [loadingModels, setLoadingModels] = (0, react_1.useState)(false);
+    const [faceDetected, setFaceDetected] = (0, react_1.useState)(false);
+    const [verifyResult, setVerifyResult] = (0, react_1.useState)(null);
+    const reportError = (0, react_1.useCallback)((msg) => {
+        if (onError)
+            onError(msg);
+        else
+            console.error('[FaceDetector]', msg);
+    }, [onError]);
+    // Load face-api models on mount
+    (0, react_1.useEffect)(() => {
+        if (!enabled)
+            return;
+        let cancelled = false;
+        async function init() {
+            setLoadingModels(true);
+            try {
+                await (0, face_api_1.loadModels)();
+                if (!cancelled)
+                    setModelsReady(true);
+            }
+            catch (err) {
+                console.error('Face-api model loading error:', err);
+                if (!cancelled)
+                    reportError('Impossible de charger les modeles de detection faciale');
+            }
+            finally {
+                if (!cancelled)
+                    setLoadingModels(false);
+            }
+        }
+        init();
+        return () => { cancelled = true; };
+    }, [enabled, reportError]);
+    // Real-time detection loop
+    const detectLoop = (0, react_1.useCallback)(async () => {
+        if (!videoRef.current || !overlayRef.current)
+            return;
+        if (videoRef.current.paused || videoRef.current.ended)
+            return;
+        const video = videoRef.current;
+        const overlay = overlayRef.current;
+        const detection = await (0, face_api_1.detectFace)(video);
+        setFaceDetected(!!detection);
+        if (!videoRef.current || !overlayRef.current)
+            return;
+        (0, face_utils_1.drawDetection)(overlay, detection, video.videoWidth, video.videoHeight);
+        animFrameRef.current = requestAnimationFrame(detectLoop);
+    }, []);
+    const startCamera = (0, react_1.useCallback)(async () => {
+        setVerifyResult(null);
+        try {
+            const stream = await navigator.mediaDevices.getUserMedia({
+                video: { width: 320, height: 240, facingMode: 'user' },
+            });
+            if (videoRef.current) {
+                videoRef.current.srcObject = stream;
+                videoRef.current.play();
+                setStreaming(true);
+                if (enabled && modelsReady) {
+                    videoRef.current.onloadeddata = () => {
+                        animFrameRef.current = requestAnimationFrame(detectLoop);
+                    };
+                }
+            }
+        }
+        catch {
+            reportError("Impossible d'acceder a la camera");
+        }
+    }, [enabled, modelsReady, detectLoop, reportError]);
+    const stopCamera = (0, react_1.useCallback)(() => {
+        cancelAnimationFrame(animFrameRef.current);
+        if (videoRef.current?.srcObject) {
+            const tracks = videoRef.current.srcObject.getTracks();
+            tracks.forEach((track) => track.stop());
+            videoRef.current.srcObject = null;
+        }
+        setStreaming(false);
+        setFaceDetected(false);
+    }, []);
+    // Cleanup on unmount
+    (0, react_1.useEffect)(() => {
+        return () => {
+            cancelAnimationFrame(animFrameRef.current);
+            if (videoRef.current?.srcObject) {
+                const tracks = videoRef.current.srcObject.getTracks();
+                tracks.forEach((track) => track.stop());
+            }
+        };
+    }, []);
+    const capturePhoto = (0, react_1.useCallback)(async () => {
+        if (!videoRef.current || !canvasRef.current)
+            return;
+        const canvas = canvasRef.current;
+        const video = videoRef.current;
+        canvas.width = video.videoWidth;
+        canvas.height = video.videoHeight;
+        const ctx = canvas.getContext('2d');
+        if (!ctx)
+            return;
+        ctx.drawImage(video, 0, 0);
+        const dataUrl = canvas.toDataURL('image/jpeg', 0.8);
+        let descriptor = null;
+        if (enabled && modelsReady) {
+            try {
+                const raw = await (0, face_api_1.extractDescriptor)(canvas);
+                if (raw)
+                    descriptor = Array.from(raw);
+            }
+            catch (err) {
+                console.error('Descriptor extraction error:', err);
+            }
+        }
+        stopCamera();
+        onCapture({ photo: dataUrl, faceDescriptor: descriptor });
+    }, [enabled, modelsReady, stopCamera, onCapture]);
+    const verifyFace = (0, react_1.useCallback)(async () => {
+        if (!videoRef.current || !verifyDescriptor)
+            return;
+        try {
+            const raw = await (0, face_api_1.extractDescriptor)(videoRef.current);
+            if (!raw) {
+                setVerifyResult(null);
+                onVerifyResult?.(null);
+                reportError('Aucun visage detecte');
+                return;
+            }
+            const distance = (0, face_matcher_1.compareFaces)(raw, verifyDescriptor);
+            const match = distance < threshold;
+            const result = { match, distance };
+            setVerifyResult(result);
+            onVerifyResult?.(result);
+        }
+        catch (err) {
+            console.error('Face verification error:', err);
+            reportError('Erreur lors de la verification');
+        }
+    }, [verifyDescriptor, onVerifyResult, threshold, reportError]);
+    const captureDisabled = enabled && requireForCapture && !faceDetected;
+    // Basic webcam mode (face detection disabled)
+    if (!enabled) {
+        return ((0, jsx_runtime_1.jsxs)("div", { style: { display: 'flex', flexDirection: 'column', gap: '1rem' }, children: [photo ? ((0, jsx_runtime_1.jsxs)("div", { style: { position: 'relative' }, children: [(0, jsx_runtime_1.jsx)("img", { src: photo, alt: "Photo", style: { width: '100%', borderRadius: '0.5rem' } }), (0, jsx_runtime_1.jsx)("button", { type: "button", onClick: onClear, style: { position: 'absolute', top: 8, right: 8, background: '#ef4444', color: 'white', border: 'none', borderRadius: '50%', width: 24, height: 24, cursor: 'pointer', fontSize: 14, lineHeight: 1 }, children: "x" })] })) : ((0, jsx_runtime_1.jsxs)("div", { style: { display: 'flex', flexDirection: 'column', gap: '0.5rem' }, children: [(0, jsx_runtime_1.jsx)("video", { ref: videoRef, style: { width: '100%', borderRadius: '0.5rem', display: streaming ? 'block' : 'none' }, autoPlay: true, playsInline: true, muted: true }), streaming ? ((0, jsx_runtime_1.jsxs)("div", { style: { display: 'flex', gap: '0.5rem' }, children: [(0, jsx_runtime_1.jsx)("button", { type: "button", onClick: capturePhoto, style: { flex: 1, padding: '0.5rem', cursor: 'pointer' }, children: "Capturer" }), (0, jsx_runtime_1.jsx)("button", { type: "button", onClick: stopCamera, style: { padding: '0.5rem', cursor: 'pointer' }, children: "x" })] })) : ((0, jsx_runtime_1.jsx)("button", { type: "button", onClick: startCamera, style: { width: '100%', padding: '0.5rem', cursor: 'pointer' }, children: "Prendre photo" }))] })), (0, jsx_runtime_1.jsx)("canvas", { ref: canvasRef, style: { display: 'none' } })] }));
+    }
+    // Full face detection mode
+    return ((0, jsx_runtime_1.jsxs)("div", { style: { display: 'flex', flexDirection: 'column', gap: '1rem' }, children: [photo ? ((0, jsx_runtime_1.jsxs)("div", { style: { position: 'relative' }, children: [(0, jsx_runtime_1.jsx)("img", { src: photo, alt: "Photo", style: { width: '100%', borderRadius: '0.5rem' } }), (0, jsx_runtime_1.jsx)("button", { type: "button", onClick: onClear, style: { position: 'absolute', top: 8, right: 8, background: '#ef4444', color: 'white', border: 'none', borderRadius: '50%', width: 24, height: 24, cursor: 'pointer', fontSize: 14, lineHeight: 1 }, children: "x" })] })) : ((0, jsx_runtime_1.jsxs)("div", { style: { display: 'flex', flexDirection: 'column', gap: '0.5rem' }, children: [(0, jsx_runtime_1.jsxs)("div", { style: { position: 'relative', display: streaming ? 'block' : 'none' }, children: [(0, jsx_runtime_1.jsx)("video", { ref: videoRef, style: { width: '100%', borderRadius: '0.5rem' }, autoPlay: true, playsInline: true, muted: true }), (0, jsx_runtime_1.jsx)("canvas", { ref: overlayRef, style: { position: 'absolute', top: 0, left: 0, width: '100%', height: '100%', pointerEvents: 'none' } }), (0, jsx_runtime_1.jsx)("div", { style: {
+                                    position: 'absolute', bottom: 8, left: 8,
+                                    padding: '2px 8px', borderRadius: 4, fontSize: 12, fontWeight: 500,
+                                    background: faceDetected ? 'rgba(34,197,94,0.9)' : 'rgba(239,68,68,0.9)',
+                                    color: 'white',
+                                }, children: faceDetected ? 'Visage detecte' : 'Aucun visage' })] }), streaming ? ((0, jsx_runtime_1.jsxs)("div", { style: { display: 'flex', gap: '0.5rem' }, children: [verifyDescriptor ? ((0, jsx_runtime_1.jsx)("button", { type: "button", onClick: verifyFace, disabled: !faceDetected, style: { flex: 1, padding: '0.5rem', cursor: faceDetected ? 'pointer' : 'not-allowed', opacity: faceDetected ? 1 : 0.5 }, children: "Verifier visage" })) : ((0, jsx_runtime_1.jsx)("button", { type: "button", onClick: capturePhoto, disabled: captureDisabled, style: { flex: 1, padding: '0.5rem', cursor: captureDisabled ? 'not-allowed' : 'pointer', opacity: captureDisabled ? 0.5 : 1 }, children: captureDisabled ? 'Cadrez votre visage...' : 'Capturer' })), (0, jsx_runtime_1.jsx)("button", { type: "button", onClick: stopCamera, style: { padding: '0.5rem', cursor: 'pointer' }, children: "x" })] })) : ((0, jsx_runtime_1.jsx)("div", { children: loadingModels ? ((0, jsx_runtime_1.jsx)("button", { type: "button", disabled: true, style: { width: '100%', padding: '0.5rem', opacity: 0.5 }, children: "Chargement detection faciale..." })) : ((0, jsx_runtime_1.jsx)("button", { type: "button", onClick: startCamera, style: { width: '100%', padding: '0.5rem', cursor: 'pointer' }, children: verifyDescriptor ? 'Verifier visage' : 'Prendre photo' })) }))] })), verifyResult && ((0, jsx_runtime_1.jsx)("div", { style: {
+                    display: 'flex', alignItems: 'center', gap: '0.5rem',
+                    padding: '0.75rem', borderRadius: '0.5rem', fontSize: 14, fontWeight: 500,
+                    background: verifyResult.match ? '#f0fdf4' : '#fef2f2',
+                    color: verifyResult.match ? '#15803d' : '#b91c1c',
+                    border: `1px solid ${verifyResult.match ? '#bbf7d0' : '#fecaca'}`,
+                }, children: verifyResult.match
+                    ? `Visage verifie (confiance: ${Math.round((1 - verifyResult.distance) * 100)}%)`
+                    : `Visage non reconnu (distance: ${verifyResult.distance.toFixed(2)})` })), (0, jsx_runtime_1.jsx)("canvas", { ref: canvasRef, style: { display: 'none' } })] }));
+}

package/dist/index.d.ts

@@ -3,4 +3,10 @@ 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 { createRecognizeHandler } from './api/recognize.route';
+export { createDetectHandler } from './api/detect.route';
+export { default as FaceDetector } from './components/FaceDetector';
+export type { FaceDetectorProps } from './components/FaceDetector';
 export type { MostaFaceConfig, FaceDetectionResult, FaceMatchResult, FaceDescriptor } from './types';
+export type { FaceCandidate, RecognizeHandlerConfig } from './api/recognize.route';
+export type { DetectHandlerConfig } from './api/detect.route';

package/dist/index.js

@@ -1,8 +1,11 @@
 "use strict";
 // @mosta/face — Barrel exports
 // Author: Dr Hamid MADANI drmdh@msn.com
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 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;
+exports.FaceDetector = exports.createDetectHandler = exports.createRecognizeHandler = 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; } });
@@ -26,3 +29,11 @@ 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; } });
+// API route factories
+var recognize_route_1 = require("./api/recognize.route");
+Object.defineProperty(exports, "createRecognizeHandler", { enumerable: true, get: function () { return recognize_route_1.createRecognizeHandler; } });
+var detect_route_1 = require("./api/detect.route");
+Object.defineProperty(exports, "createDetectHandler", { enumerable: true, get: function () { return detect_route_1.createDetectHandler; } });
+// Components
+var FaceDetector_1 = require("./components/FaceDetector");
+Object.defineProperty(exports, "FaceDetector", { enumerable: true, get: function () { return __importDefault(FaceDetector_1).default; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mostajs/face",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Reusable face recognition module — detection, descriptor extraction, 1:N matching",
   "author": "Dr Hamid MADANI <drmdh@msn.com>",
   "license": "MIT",
@@ -24,6 +24,41 @@
       "import": "./dist/hooks/useFaceDetection.js",
       "require": "./dist/hooks/useFaceDetection.js",
       "default": "./dist/hooks/useFaceDetection.js"
+    },
+    "./components/FaceDetector": {
+      "types": "./dist/components/FaceDetector.d.ts",
+      "import": "./dist/components/FaceDetector.js",
+      "default": "./dist/components/FaceDetector.js"
+    },
+    "./lib/face-api": {
+      "types": "./dist/lib/face-api.d.ts",
+      "import": "./dist/lib/face-api.js",
+      "default": "./dist/lib/face-api.js"
+    },
+    "./lib/face-matcher": {
+      "types": "./dist/lib/face-matcher.d.ts",
+      "import": "./dist/lib/face-matcher.js",
+      "default": "./dist/lib/face-matcher.js"
+    },
+    "./lib/face-utils": {
+      "types": "./dist/lib/face-utils.d.ts",
+      "import": "./dist/lib/face-utils.js",
+      "default": "./dist/lib/face-utils.js"
+    },
+    "./api/recognize.route": {
+      "types": "./dist/api/recognize.route.d.ts",
+      "import": "./dist/api/recognize.route.js",
+      "default": "./dist/api/recognize.route.js"
+    },
+    "./api/detect.route": {
+      "types": "./dist/api/detect.route.d.ts",
+      "import": "./dist/api/detect.route.js",
+      "default": "./dist/api/detect.route.js"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/types/index.js",
+      "default": "./dist/types/index.js"
     }
   },
   "files": ["dist", "LICENSE", "README.md"],