@mostajs/face 1.3.7 → 1.4.0

package/browser/mosta-face.js

@@ -0,0 +1,33 @@
+/* @mostajs/face — helper navigateur autonome (window.MostaFace).
+ * À charger APRÈS browser/face-api.js (global `faceapi`). Sur le modèle de
+ * @mostajs/qrpanel/browser-scan, mais face-api reste un FICHIER SÉPARÉ vendu dans
+ * le module (browser/face-api.js), non concaténé. Aucune dépendance CDN ni build.
+ * @author Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later */
+(function () {
+  if (typeof faceapi === 'undefined') { console.warn('[MostaFace] browser/face-api.js doit être chargé avant mosta-face.js'); return; }
+  var loaded = false;
+  async function loadModels(uri) {
+    if (loaded) return;
+    uri = uri || '/static/models/face-api';
+    await faceapi.nets.tinyFaceDetector.loadFromUri(uri);
+    await faceapi.nets.faceLandmark68Net.loadFromUri(uri);
+    await faceapi.nets.faceRecognitionNet.loadFromUri(uri);
+    loaded = true;
+  }
+  async function startCamera(video, opts) {
+    var stream = await navigator.mediaDevices.getUserMedia({ video: Object.assign({ facingMode: 'user', width: 480, height: 360 }, opts || {}) });
+    video.srcObject = stream; await video.play(); return stream;
+  }
+  async function detect(video) {
+    return faceapi.detectSingleFace(video, new faceapi.TinyFaceDetectorOptions()).withFaceLandmarks().withFaceDescriptor();
+  }
+  async function captureDescriptor(video) { var d = await detect(video); return d ? Array.from(d.descriptor) : null; }
+  function snapshot(video, q) {
+    var c = document.createElement('canvas'); c.width = video.videoWidth || 480; c.height = video.videoHeight || 360;
+    c.getContext('2d').drawImage(video, 0, 0, c.width, c.height); return c.toDataURL('image/jpeg', q || 0.7);
+  }
+  window.MostaFace = {
+    loadModels: loadModels, startCamera: startCamera, detect: detect,
+    captureDescriptor: captureDescriptor, snapshot: snapshot, isLoaded: function () { return loaded; },
+  };
+})();

package/llms.txt

@@ -0,0 +1,118 @@
+# @mostajs/face — fiche LLM
+> Reconnaissance faciale réutilisable : détection, extraction de descripteur 128-D, matching 1:N, hooks React et factories de routes API.
+
+- Version: 1.3.7 · Licence: AGPL-3.0-or-later · Auteur: Dr Hamid MADANI <drmdh@msn.com>
+- Chemin: mostajs/mosta-face · Statut audit: complet (dist/)
+
+## RÔLE
+Module de reconnaissance faciale de l'écosystème mostajs, bâti sur @vladmandic/face-api. Détecte les visages, extrait le descripteur facial 128 dimensions, compare des descripteurs (distance euclidienne) et effectue du matching 1:N contre une liste de candidats. Fournit des hooks React (accès caméra, détection en boucle), un composant FaceDetector, et des factories de routes API Next.js (recognize, detect). Module 100% autonome : aucune dépendance sur `@mostajs/orm` ni un autre package @mostajs/*. La détection s'exécute côté client (browser) ; le serveur ne fait que le gating de permission et le matching.
+
+## INSTALLATION
+npm i @mostajs/face
+# Puis copier les modèles face-api.js dans public/models/face-api/ :
+# tiny_face_detector, face_landmark_68, face_recognition (fichiers .bin + .json
+# depuis node_modules/@vladmandic/face-api/model/)
+
+## EXPORTS
+Point d'entrée racine (`.`) :
+- Core face-api: loadModels, isLoaded, detectFace, detectAllFaces, extractDescriptor
+- Matching: compareFaces, findMatch, findAllMatches
+- Utils: descriptorToArray, arrayToDescriptor, isValidDescriptor, drawDetection
+- Hooks: useCamera, useFaceDetection
+- API factories: createRecognizeHandler, createDetectHandler
+- Composant: FaceDetector (default)
+- Menu: faceMenuContribution
+- Constante: DEFAULT_FACE_SETTINGS
+- Types: MostaFaceConfig, FaceDetectionResult, FaceMatchResult, FaceDescriptor, FaceSettings, FaceDetectorProps, FaceCandidate, RecognizeHandlerConfig, DetectHandlerConfig
+
+## EXPORTS PAR SOUS-CHEMIN
+- `./lib/face-api` — loadModels, isLoaded, detectFace, detectAllFaces, extractDescriptor
+- `./lib/face-matcher` — compareFaces, findMatch, findAllMatches
+- `./lib/face-utils` — descriptorToArray, arrayToDescriptor, isValidDescriptor, drawDetection
+- `./lib/menu` — faceMenuContribution
+- `./hooks/useCamera` — useCamera
+- `./hooks/useFaceDetection` — useFaceDetection
+- `./components/FaceDetector` — composant React (default)
+- `./api/recognize.route` — createRecognizeHandler ; types FaceCandidate, RecognizeHandlerConfig
+- `./api/detect.route` — createDetectHandler ; type DetectHandlerConfig
+- `./types` — tous les types + DEFAULT_FACE_SETTINGS
+- `./register` — register(registry)
+- **ASSETS NAVIGATEUR AUTONOMES** (sur le modèle de `@mostajs/qrpanel/browser-scan`, **sans CDN ni build**) — face-api est **vendu comme fichier source du module** (PAS bundlé/concaténé) :
+  - `./browser/face-api.js` — source @vladmandic/face-api (global `faceapi`), copié dans le module (LICENSE: `browser/face-api.LICENSE`).
+  - `./browser/mosta-face.js` — helper `window.MostaFace`, fichier SÉPARÉ, à charger APRÈS face-api.js.
+  - Chargement app : `<script src="/static/face-api.js"></script><script src="/static/mosta-face.js"></script>` + servir les modèles sous `/static/models/face-api/`.
+  - `window.MostaFace`: `loadModels(uri?)`, `startCamera(video, opts?)`, `detect(video)`, `captureDescriptor(video) -> number[]|null`, `snapshot(video, q?) -> dataURL`, `isLoaded()`.
+
+## API — SIGNATURES
+loadModels(config?: MostaFaceConfig): Promise<void>  // charge face-api.js + 3 modèles
+isLoaded(): boolean
+detectFace(input: HTMLVideoElement|HTMLCanvasElement, config?): Promise<WithFaceLandmarks|null>
+detectAllFaces(input, config?): Promise<WithFaceLandmarks[]>
+extractDescriptor(input, config?): Promise<Float32Array|null>  // descripteur 128-D
+compareFaces(d1: FaceDescriptor, d2: FaceDescriptor): number  // distance euclidienne
+findMatch<T extends {faceDescriptor:number[]}>(descriptor, candidates: T[], threshold?): FaceMatchResult<T>|null
+findAllMatches<T extends {faceDescriptor:number[]}>(descriptor, candidates, threshold?): FaceMatchResult<T>[]  // trié par distance
+descriptorToArray(d: Float32Array): number[]  · arrayToDescriptor(arr: number[]): Float32Array
+isValidDescriptor(data: unknown): boolean  // vrai si 128 éléments
+drawDetection(canvas, detection|null, videoWidth, videoHeight): void
+useCamera(options?: { facingMode?, width?, height?, autoStart? }): { videoRef, stream, status, error, start, stop, switchCamera }
+useFaceDetection(videoRef, options?: { interval?, autoStart?, extractDescriptor?, config? }): { detection, descriptor, status, modelsLoaded, start, stop }
+createRecognizeHandler(config: RecognizeHandlerConfig): { POST }  // POST /api/face/recognize
+createDetectHandler(config?: DetectHandlerConfig): { POST }  // POST /api/face/detect (placeholder, gating)
+
+## TYPES CLÉS
+MostaFaceConfig { modelsPath?('/models/face-api'), scoreThreshold?(0.5), inputSize?(320), matchThreshold?(0.6) }
+FaceDescriptor = Float32Array | number[]
+FaceDetectionResult { detection:{ score, box:{x,y,width,height} }, landmarks? }
+FaceMatchResult<T> { match: T, distance: number }
+FaceSettings { faceRecognitionEnabled, faceRecognitionThreshold(0.6), faceRequireForCapture, faceAutoVerify }
+DEFAULT_FACE_SETTINGS — valeurs par défaut de FaceSettings
+FaceCandidate { id, faceDescriptor: number[], [key: string]: unknown }
+RecognizeHandlerConfig { getCandidates()=>Promise<FaceCandidate[]>, checkAuth?(req)=>Promise<Response|null>, getThreshold?()=>Promise<number>, isEnabled?()=>Promise<boolean>, publicFields?:string[] }
+DetectHandlerConfig { checkAuth?(req)=>Promise<Response|null>, isEnabled?()=>Promise<boolean> }
+CameraStatus = 'idle'|'requesting'|'active'|'denied'|'error'
+DetectionStatus = 'loading'|'detecting'|'detected'|'noFace'
+
+## PATTERN
+```ts
+// Client — détection + extraction
+import { loadModels, extractDescriptor, descriptorToArray } from '@mostajs/face'
+await loadModels({ modelsPath: '/models/face-api' })
+const d = await extractDescriptor(videoEl)          // Float32Array 128-D
+const stored = descriptorToArray(d)                 // number[] pour DB/JSON
+
+// Client — hooks React
+import { useCamera, useFaceDetection } from '@mostajs/face'
+const { videoRef, start } = useCamera({ autoStart: true })
+const { descriptor, status } = useFaceDetection(videoRef, { extractDescriptor: true })
+
+// Matching 1:N
+import { findMatch } from '@mostajs/face'
+const result = findMatch(descriptor, candidates, 0.6)  // null si rien sous le seuil
+
+// Serveur — route Next.js
+import { createRecognizeHandler } from '@mostajs/face/api/recognize.route'
+export const { POST } = createRecognizeHandler({
+  getCandidates: async () => clientRepo.findAll({ status:'active' }, { select:['firstName','faceDescriptor'] }),
+  getThreshold: async () => 0.6,
+})
+```
+
+## DÉPEND DE
+- @vladmandic/face-api (dependency) — moteur de détection/reconnaissance.
+- Aucun module @mostajs/* requis (module 100% autonome).
+- Peers : react >=18 ; @mostajs/menu (optionnel), @mostajs/socle (>=2.0.0, pour register).
+
+## PIÈGES
+- Les modèles face-api.js NE sont PAS embarqués : il faut copier manuellement les 3 modèles (tiny_face_detector, face_landmark_68, face_recognition) dans `public/models/face-api/` (ou modelsPath custom) sinon loadModels échoue.
+- loadModels doit être appelé (et terminé) avant detectFace/extractDescriptor — vérifier isLoaded() ou attendre la promesse.
+- La détection s'exécute CÔTÉ CLIENT (browser, via HTMLVideoElement/HTMLCanvasElement) ; createDetectHandler est un placeholder de gating, il ne détecte pas de visage côté serveur.
+- Le matching utilise la distance euclidienne : seuil PLUS BAS = PLUS strict (défaut 0.6). findMatch renvoie null si aucun candidat n'est sous le seuil.
+- Les descripteurs se stockent en `number[]` (descriptorToArray) pour JSON/DB et se reconvertissent en Float32Array (arrayToDescriptor) avant comparaison.
+- Un descripteur valide a exactement 128 éléments (isValidDescriptor).
+- createRecognizeHandler n'authentifie pas par défaut : fournir une callback `checkAuth` retournant une Response pour refuser, ou null pour laisser passer ; par défaut publicFields exclut faceDescriptor de la réponse.
+
+## RÉFÉRENCES
+- README.md (racine du module) — quick start, intégration complète, API reference
+- face.wire.json, wire.json — déclaration de câblage
+- LICENSE (AGPL-3.0-or-later)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mostajs/face",
-  "version": "1.3.7",
+  "version": "1.4.0",
   "description": "Reusable face recognition module — detection, descriptor extraction, 1:N matching",
   "author": "Dr Hamid MADANI <drmdh@msn.com>",
   "license": "AGPL-3.0-or-later",
@@ -69,14 +69,18 @@
       "types": "./dist/register.d.ts",
       "import": "./dist/register.js",
       "default": "./dist/register.js"
-    }
+    },
+    "./browser/face-api.js": "./browser/face-api.js",
+    "./browser/mosta-face.js": "./browser/mosta-face.js"
   },
   "files": [
     "dist",
     "wire.json",
     "face.wire.json",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "llms.txt",
+    "browser"
   ],
   "keywords": [
     "face-recognition",
@@ -94,10 +98,6 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "scripts": {
-    "build": "tsc",
-    "prepublishOnly": "npm run build"
-  },
   "dependencies": {
     "@vladmandic/face-api": "^1.7.0"
   },
@@ -117,5 +117,8 @@
     "@mostajs/menu": {
       "optional": true
     }
+  },
+  "scripts": {
+    "build": "tsc"
   }
-}
+}