alphavalid-sdk 0.0.4 → 0.0.6

package/dist/core/camera.d.ts

@@ -0,0 +1,8 @@
+export interface CameraHandle {
+    video: HTMLVideoElement;
+    stream: MediaStream;
+    stop: () => void;
+}
+export declare function startUserCamera(container: HTMLElement): Promise<CameraHandle>;
+export declare function captureVideoFrameToJpegBlob(video: HTMLVideoElement, quality?: number): Promise<Blob>;
+//# sourceMappingURL=camera.d.ts.map

package/dist/core/camera.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"camera.d.ts","sourceRoot":"","sources":["../../src/core/camera.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,gBAAgB,CAAC;IACxB,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,wBAAsB,eAAe,CAAC,SAAS,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CA0CnF;AAED,wBAAsB,2BAA2B,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,SAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBvG"}

package/dist/core/feedback.d.ts

@@ -0,0 +1,7 @@
+import type { AlphaValidFeedbackMessage, FaceDetectionStatus } from '../types/sdk';
+export interface FeedbackResult {
+    message: AlphaValidFeedbackMessage;
+    valid: boolean;
+}
+export declare function computeFeedback(status: FaceDetectionStatus): FeedbackResult;
+//# sourceMappingURL=feedback.d.ts.map

package/dist/core/feedback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback.d.ts","sourceRoot":"","sources":["../../src/core/feedback.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEnF,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,yBAAyB,CAAC;IACnC,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,mBAAmB,GAAG,cAAc,CA6B3E"}

package/dist/index.d.ts

@@ -1,6 +1,17 @@
+import type { AlphaValidStartOptions } from './types/sdk';
 export declare class AlphaValid {
-    private video;
-    start(options: any): Promise<void>;
+    private _camera;
+    private _overlay;
+    private _container;
+    private _faceDetector;
+    private _loopTimer;
+    private _lastStatusValid;
+    private _options;
+    start(options: AlphaValidStartOptions): Promise<void>;
+    /** Stop camera + overlay + detection loop */
+    stop(): Promise<void>;
     capture(): Promise<Blob>;
+    private startDetectionLoop;
 }
+export type { AlphaValidStartOptions } from './types/sdk';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAoB;IAE3B,KAAK,CAAC,OAAO,EAAE,GAAG;IAalB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAY/B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAO1D,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,UAAU,CAA4B;IAC9C,OAAO,CAAC,aAAa,CAAsC;IAC3D,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAuC;IAEjD,KAAK,CAAC,OAAO,EAAE,sBAAsB;IAwC3C,6CAA6C;IACvC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAsBrB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAW9B,OAAO,CAAC,kBAAkB;CA2B3B;AAED,YAAY,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC"}

package/dist/types/sdk.d.ts

@@ -0,0 +1,29 @@
+export type AlphaValidFeedbackMessage = 'Inicializando câmera...' | 'Centralize seu rosto' | 'Aproxime o rosto' | 'Afaste o rosto' | 'Ajuste a iluminação' | 'Apenas 1 rosto por vez' | 'Rosto detectado' | 'Pronto para capturar';
+export interface AlphaValidStartOptions {
+    container: HTMLElement;
+    /** Called when the camera stream is attached and video can play. */
+    onReady?: () => void;
+    /** Called frequently as face detection runs, to guide the user. */
+    onFeedback?: (message: AlphaValidFeedbackMessage) => void;
+    /** Called on errors (permission denied, no camera, etc). */
+    onError?: (error: unknown) => void;
+    /** Optional: enable/disable overlay guide (default true). */
+    overlay?: boolean;
+    /** Optional: circle size ratio (0-1). Default 0.72 of the smallest side. */
+    guideCircleRatio?: number;
+    /** How often to run face detection (ms). Default 200. */
+    detectionIntervalMs?: number;
+    /** Provide face-api models base URL (must contain /tiny_face_detector_model-weights_manifest.json etc). */
+    modelsPath?: string;
+}
+export interface FaceDetectionStatus {
+    faces: number;
+    /** Face box normalized [0..1] relative to video square viewport. */
+    box?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+//# sourceMappingURL=sdk.d.ts.map

package/dist/types/sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../src/types/sdk.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,yBAAyB,GACjC,yBAAyB,GACzB,sBAAsB,GACtB,kBAAkB,GAClB,gBAAgB,GAChB,qBAAqB,GACrB,wBAAwB,GACxB,iBAAiB,GACjB,sBAAsB,CAAC;AAE3B,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,WAAW,CAAC;IAEvB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAErB,mEAAmE;IACnE,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,IAAI,CAAC;IAE1D,4DAA4D;IAC5D,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAEnC,6DAA6D;IAC7D,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,yDAAyD;IACzD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B,2GAA2G;IAC3G,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,GAAG,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/D"}

package/dist/ui/overlay.d.ts

@@ -0,0 +1,16 @@
+export interface OverlayHandle {
+    canvas: HTMLCanvasElement;
+    dispose: () => void;
+    render: (status: {
+        message?: string;
+        box?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        valid?: boolean;
+    }) => void;
+}
+export declare function createOverlay(container: HTMLElement, guideCircleRatio?: number): OverlayHandle;
+//# sourceMappingURL=overlay.d.ts.map

package/dist/ui/overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../../src/ui/overlay.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,MAAM,EAAE,CAAC,MAAM,EAAE;QACf,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,GAAG,CAAC,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC;QAC9D,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,KAAK,IAAI,CAAC;CACZ;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,WAAW,EAAE,gBAAgB,SAAO,GAAG,aAAa,CAkF5F"}

package/dist/utils/dom.d.ts

@@ -0,0 +1,3 @@
+export declare function ensureHTMLElement(el: unknown, name: string): asserts el is HTMLElement;
+export declare function cleanupElement(el: HTMLElement | null | undefined): void;
+//# sourceMappingURL=dom.d.ts.map

package/dist/utils/dom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../../src/utils/dom.ts"],"names":[],"mappings":"AAAA,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,EAAE,IAAI,WAAW,CAItF;AAED,wBAAgB,cAAc,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAOvE"}

package/dist/vision/faceDetector.d.ts

@@ -0,0 +1,7 @@
+import type { FaceDetectionStatus } from '../types/sdk';
+export interface FaceDetector {
+    load: (modelsPath: string) => Promise<void>;
+    detect: (video: HTMLVideoElement) => Promise<FaceDetectionStatus>;
+}
+export declare function createFaceDetector(): FaceDetector;
+//# sourceMappingURL=faceDetector.d.ts.map

package/dist/vision/faceDetector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"faceDetector.d.ts","sourceRoot":"","sources":["../../src/vision/faceDetector.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAExD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACnE;AAED,wBAAgB,kBAAkB,IAAI,YAAY,CAwCjD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alphavalid-sdk",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "SDK de validação facial e liveness",
   "main": "dist/alphavalid.umd.js",
   "module": "dist/alphavalid.es.js",
@@ -8,7 +8,11 @@
   "scripts": {
     "build": "npx vite build",
     "types": "tsc -p tsconfig.json",
-    "build:all": "rm -rf dist && npm run build && npm run types"
+    "build:all": "rm -rf dist && npm run build && npm run types",
+    "test:local": "vite preview"
+  },
+  "dependencies": {
+    "face-api.js": "^0.22.2"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",

package/src/core/camera.ts

@@ -0,0 +1,69 @@
+export interface CameraHandle {
+  video: HTMLVideoElement;
+  stream: MediaStream;
+  stop: () => void;
+}
+
+export async function startUserCamera(container: HTMLElement): Promise<CameraHandle> {
+  const stream = await navigator.mediaDevices.getUserMedia({
+    video: { facingMode: 'user' }
+  });
+
+  const video = document.createElement('video');
+  video.autoplay = true;
+  video.playsInline = true;
+  video.muted = true;
+  video.srcObject = stream;
+
+  // Make it fill container; user can override via CSS
+  video.style.width = '100%';
+  video.style.height = '100%';
+  video.style.objectFit = 'cover';
+
+  container.appendChild(video);
+
+  await new Promise<void>((resolve, reject) => {
+    const onLoaded = () => {
+      video.removeEventListener('loadedmetadata', onLoaded);
+      resolve();
+    };
+    const onError = () => {
+      video.removeEventListener('error', onError);
+      reject(new Error('Failed to load camera stream into video element'));
+    };
+    video.addEventListener('loadedmetadata', onLoaded);
+    video.addEventListener('error', onError);
+  });
+
+  const stop = () => {
+    stream.getTracks().forEach((t) => t.stop());
+    try {
+      (video as HTMLVideoElement & { srcObject: MediaStream | null }).srcObject = null;
+    } catch {
+      // ignore
+    }
+    if (video.parentElement) video.parentElement.removeChild(video);
+  };
+
+  return { video, stream, stop };
+}
+
+export async function captureVideoFrameToJpegBlob(video: HTMLVideoElement, quality = 0.9): Promise<Blob> {
+  const canvas = document.createElement('canvas');
+  canvas.width = video.videoWidth;
+  canvas.height = video.videoHeight;
+
+  const ctx = canvas.getContext('2d');
+  ctx?.drawImage(video, 0, 0);
+
+  return await new Promise<Blob>((resolve, reject) => {
+    canvas.toBlob(
+      (blob) => {
+        if (!blob) return reject(new Error('Failed to capture image blob'));
+        resolve(blob);
+      },
+      'image/jpeg',
+      quality
+    );
+  });
+}

package/src/core/feedback.ts

@@ -0,0 +1,37 @@
+import type { AlphaValidFeedbackMessage, FaceDetectionStatus } from '../types/sdk';
+
+export interface FeedbackResult {
+  message: AlphaValidFeedbackMessage;
+  valid: boolean;
+}
+
+export function computeFeedback(status: FaceDetectionStatus): FeedbackResult {
+  if (status.faces === 0) {
+    return { message: 'Centralize seu rosto', valid: false };
+  }
+
+  if (status.faces > 1) {
+    return { message: 'Apenas 1 rosto por vez', valid: false };
+  }
+
+  if (!status.box) {
+    return { message: 'Centralize seu rosto', valid: false };
+  }
+
+  // Positioning rules (simple heuristics)
+  const { x, y, width, height } = status.box;
+  const cx = x + width / 2;
+  const cy = y + height / 2;
+
+  // Size thresholds (normalized)
+  const faceArea = width * height;
+  if (faceArea < 0.07) return { message: 'Aproxime o rosto', valid: false };
+  if (faceArea > 0.22) return { message: 'Afaste o rosto', valid: false };
+
+  // Centering thresholds
+  if (Math.abs(cx - 0.5) > 0.12 || Math.abs(cy - 0.5) > 0.12) {
+    return { message: 'Centralize seu rosto', valid: false };
+  }
+
+  return { message: 'Pronto para capturar', valid: true };
+}

package/src/index.ts

@@ -1,29 +1,120 @@
+import type { AlphaValidStartOptions } from './types/sdk';
+import { ensureHTMLElement } from './utils/dom';
+import { startUserCamera, captureVideoFrameToJpegBlob, type CameraHandle } from './core/camera';
+import { createOverlay, type OverlayHandle } from './ui/overlay';
+import { createFaceDetector, type FaceDetector } from './vision/faceDetector';
+import { computeFeedback } from './core/feedback';
+
 export class AlphaValid {
-  private video!: HTMLVideoElement;
+  private _camera: CameraHandle | null = null;
+  private _overlay: OverlayHandle | null = null;
+  private _container: HTMLElement | null = null;
+  private _faceDetector: FaceDetector = createFaceDetector();
+  private _loopTimer: number | null = null;
+  private _lastStatusValid = false;
+  private _options: AlphaValidStartOptions | null = null;
+
+  async start(options: AlphaValidStartOptions) {
+    ensureHTMLElement(options.container, 'options.container');
+
+    // Stop any existing session
+    await this.stop();
+
+    this._options = {
+      overlay: true,
+      guideCircleRatio: 0.72,
+      detectionIntervalMs: 200,
+      modelsPath: '/models',
+      ...options
+    };
+
+    this._container = this._options.container;
+
+    try {
+      this._options.onFeedback?.('Inicializando câmera...');
 
-  async start(options: any) {
-    const stream = await navigator.mediaDevices.getUserMedia({
-      video: { facingMode: "user" }
-    });
+      this._camera = await startUserCamera(this._container);
 
-    this.video = document.createElement("video");
-    this.video.srcObject = stream;
-    this.video.autoplay = true;
-    this.video.playsInline = true;
+      if (this._options.overlay !== false) {
+        this._overlay = createOverlay(this._container, this._options.guideCircleRatio);
+      }
 
-    options.container.appendChild(this.video);
+      this._options.onReady?.();
+
+      // Face-api models (user must host them)
+      if (this._options.modelsPath) {
+        await this._faceDetector.load(this._options.modelsPath);
+      }
+
+      this.startDetectionLoop();
+    } catch (err) {
+      this._options?.onError?.(err);
+      await this.stop();
+      throw err;
+    }
+  }
+
+  /** Stop camera + overlay + detection loop */
+  async stop(): Promise<void> {
+    if (this._loopTimer != null) {
+      window.clearTimeout(this._loopTimer);
+      this._loopTimer = null;
+    }
+
+    this._lastStatusValid = false;
+
+    if (this._overlay) {
+      this._overlay.dispose();
+      this._overlay = null;
+    }
+
+    if (this._camera) {
+      this._camera.stop();
+      this._camera = null;
+    }
+
+    this._container = null;
+    this._options = null;
   }
 
   async capture(): Promise<Blob> {
-    const canvas = document.createElement("canvas");
-    canvas.width = this.video.videoWidth;
-    canvas.height = this.video.videoHeight;
+    if (!this._camera) throw new Error('Camera not started. Call start() first.');
+
+    // Optional: enforce valid pose before capture
+    if (!this._lastStatusValid) {
+      throw new Error('Face not valid for capture yet. Wait for feedback "Pronto para capturar".');
+    }
+
+    return await captureVideoFrameToJpegBlob(this._camera.video, 0.9);
+  }
+
+  private startDetectionLoop(): void {
+    const tick = async () => {
+      const camera = this._camera;
+      const options = this._options;
+
+      if (!camera || !options) return;
 
-    const ctx = canvas.getContext("2d");
-    ctx?.drawImage(this.video, 0, 0);
+      try {
+        const status = await this._faceDetector.detect(camera.video);
+        const fb = computeFeedback(status);
+        this._lastStatusValid = fb.valid;
 
-    return new Promise((resolve) => {
-      canvas.toBlob((blob) => resolve(blob!), "image/jpeg");
-    });
+        options.onFeedback?.(fb.message);
+        this._overlay?.render({
+          message: fb.message,
+          box: status.box,
+          valid: fb.valid
+        });
+      } catch (err) {
+        options.onError?.(err);
+      } finally {
+        this._loopTimer = window.setTimeout(tick, options.detectionIntervalMs ?? 200);
+      }
+    };
+
+    void tick();
   }
-}
+}
+
+export type { AlphaValidStartOptions } from './types/sdk';

package/src/types/sdk.ts

@@ -0,0 +1,40 @@
+export type AlphaValidFeedbackMessage =
+  | 'Inicializando câmera...'
+  | 'Centralize seu rosto'
+  | 'Aproxime o rosto'
+  | 'Afaste o rosto'
+  | 'Ajuste a iluminação'
+  | 'Apenas 1 rosto por vez'
+  | 'Rosto detectado'
+  | 'Pronto para capturar';
+
+export interface AlphaValidStartOptions {
+  container: HTMLElement;
+
+  /** Called when the camera stream is attached and video can play. */
+  onReady?: () => void;
+
+  /** Called frequently as face detection runs, to guide the user. */
+  onFeedback?: (message: AlphaValidFeedbackMessage) => void;
+
+  /** Called on errors (permission denied, no camera, etc). */
+  onError?: (error: unknown) => void;
+
+  /** Optional: enable/disable overlay guide (default true). */
+  overlay?: boolean;
+
+  /** Optional: circle size ratio (0-1). Default 0.72 of the smallest side. */
+  guideCircleRatio?: number;
+
+  /** How often to run face detection (ms). Default 200. */
+  detectionIntervalMs?: number;
+
+  /** Provide face-api models base URL (must contain /tiny_face_detector_model-weights_manifest.json etc). */
+  modelsPath?: string;
+}
+
+export interface FaceDetectionStatus {
+  faces: number;
+  /** Face box normalized [0..1] relative to video square viewport. */
+  box?: { x: number; y: number; width: number; height: number };
+}

package/src/ui/overlay.ts

@@ -0,0 +1,93 @@
+export interface OverlayHandle {
+  canvas: HTMLCanvasElement;
+  dispose: () => void;
+  render: (status: {
+    message?: string;
+    box?: { x: number; y: number; width: number; height: number };
+    valid?: boolean;
+  }) => void;
+}
+
+export function createOverlay(container: HTMLElement, guideCircleRatio = 0.72): OverlayHandle {
+  const canvas = document.createElement('canvas');
+  const ctx = canvas.getContext('2d');
+
+  canvas.style.position = 'absolute';
+  canvas.style.left = '0';
+  canvas.style.top = '0';
+  canvas.style.width = '100%';
+  canvas.style.height = '100%';
+  canvas.style.pointerEvents = 'none';
+
+  const prevPos = getComputedStyle(container).position;
+  if (prevPos === 'static') {
+    container.style.position = 'relative';
+  }
+
+  container.appendChild(canvas);
+
+  const resizeToContainer = () => {
+    const rect = container.getBoundingClientRect();
+    canvas.width = Math.max(1, Math.round(rect.width));
+    canvas.height = Math.max(1, Math.round(rect.height));
+  };
+
+  const draw = (status: Parameters<OverlayHandle['render']>[0]) => {
+    if (!ctx) return;
+    resizeToContainer();
+
+    const w = canvas.width;
+    const h = canvas.height;
+
+    ctx.clearRect(0, 0, w, h);
+
+    // Dark backdrop
+    ctx.fillStyle = 'rgba(0,0,0,0.45)';
+    ctx.fillRect(0, 0, w, h);
+
+    // "Hole" circle
+    const r = Math.min(w, h) * guideCircleRatio * 0.5;
+    const cx = w / 2;
+    const cy = h / 2;
+
+    ctx.globalCompositeOperation = 'destination-out';
+    ctx.beginPath();
+    ctx.arc(cx, cy, r, 0, Math.PI * 2);
+    ctx.fill();
+    ctx.globalCompositeOperation = 'source-over';
+
+    // Circle stroke
+    ctx.lineWidth = 4;
+    ctx.strokeStyle = status.valid ? 'rgba(46, 204, 113, 0.95)' : 'rgba(255,255,255,0.9)';
+    ctx.beginPath();
+    ctx.arc(cx, cy, r, 0, Math.PI * 2);
+    ctx.stroke();
+
+    // Face box (optional, normalized)
+    if (status.box) {
+      ctx.lineWidth = 2;
+      ctx.strokeStyle = 'rgba(52, 152, 219, 0.9)';
+      ctx.strokeRect(status.box.x * w, status.box.y * h, status.box.width * w, status.box.height * h);
+    }
+
+    // Text
+    if (status.message) {
+      ctx.fillStyle = 'rgba(0,0,0,0.6)';
+      const pad = 10;
+      const boxH = 44;
+      ctx.fillRect(0, h - boxH, w, boxH);
+
+      ctx.fillStyle = 'white';
+      ctx.font = '16px system-ui, -apple-system, Segoe UI, Roboto, Arial';
+      ctx.textAlign = 'center';
+      ctx.textBaseline = 'middle';
+      ctx.fillText(status.message, w / 2, h - boxH / 2);
+    }
+  };
+
+  const dispose = () => {
+    if (canvas.parentElement) canvas.parentElement.removeChild(canvas);
+  };
+
+  return { canvas, dispose, render: draw };
+}

package/src/utils/dom.ts

@@ -0,0 +1,14 @@
+export function ensureHTMLElement(el: unknown, name: string): asserts el is HTMLElement {
+  if (!(el instanceof HTMLElement)) {
+    throw new Error(`${name} must be an HTMLElement`);
+  }
+}
+
+export function cleanupElement(el: HTMLElement | null | undefined): void {
+  if (!el) return;
+  try {
+    el.remove();
+  } catch {
+    // ignore
+  }
+}

package/src/vision/faceDetector.ts

@@ -0,0 +1,49 @@
+import * as faceapi from 'face-api.js';
+import type { FaceDetectionStatus } from '../types/sdk';
+
+export interface FaceDetector {
+  load: (modelsPath: string) => Promise<void>;
+  detect: (video: HTMLVideoElement) => Promise<FaceDetectionStatus>;
+}
+
+export function createFaceDetector(): FaceDetector {
+  let loaded = false;
+
+  const load = async (modelsPath: string) => {
+    if (loaded) return;
+
+    // tinyFaceDetector is the lightest for MVP.
+    await faceapi.nets.tinyFaceDetector.loadFromUri(modelsPath);
+    loaded = true;
+  };
+
+  const detect = async (video: HTMLVideoElement): Promise<FaceDetectionStatus> => {
+    if (!loaded) {
+      return { faces: 0 };
+    }
+
+    const result = await faceapi.detectAllFaces(
+      video,
+      new faceapi.TinyFaceDetectorOptions({ inputSize: 224, scoreThreshold: 0.5 })
+    );
+
+    if (!result || result.length === 0) return { faces: 0 };
+    if (result.length > 1) return { faces: result.length };
+
+    const box = result[0].box;
+    const vw = video.videoWidth || 1;
+    const vh = video.videoHeight || 1;
+
+    return {
+      faces: 1,
+      box: {
+        x: box.x / vw,
+        y: box.y / vh,
+        width: box.width / vw,
+        height: box.height / vh
+      }
+    };
+  };
+
+  return { load, detect };
+}