@incodetech/core 2.1.1 → 2.2.0-rc.1

package/dist/face-match.esm.js

@@ -1,173 +1,3 @@
-import "./api-DsbUi7TO.esm.js";
-import { n as eventModuleNames, s as createManagerInstrumentation } from "./events-1wxZ97yf.esm.js";
-import "./endpoints-CwrFQfW7.esm.js";
-import { l as createManager, s as createActor } from "./xstate.esm-nY3M5UYm.esm.js";
-import { n as ID_FACE_EXTRACTION_SKIPPED_CODE, r as isFaceExtractionSkippedError, t as faceMatchMachine } from "./faceMatchStateMachine-MDb30gCm.esm.js";
-
-//#region src/modules/face-match/faceMatchActor.ts
-function createFaceMatchActor(options) {
-	return createActor(faceMatchMachine, { input: { config: options.config } }).start();
-}
-
-//#endregion
-//#region src/modules/face-match/faceMatchManager.ts
-/**
-* @module @incodetech/core/face-match
-*
-* Face match module for the Incode Web SDK.
-* Supports both headless (programmatic) and UI-driven usage patterns.
-*
-* ## Headless Usage
-*
-* The face match manager can be used entirely without UI for backend integrations,
-* custom UI implementations, or automated workflows.
-*
-* @example Basic headless face match with auto-skip
-* ```typescript
-* import { createFaceMatchManager } from '@incodetech/core/face-match';
-* import { setup } from '@incodetech/core';
-*
-* // 1. Configure the SDK (required before using any module)
-* setup({ apiURL: 'https://api.example.com', token: 'your-token' });
-*
-* // 2. Create the face match manager
-* const faceMatchManager = createFaceMatchManager({
-*   config: {
-*     matchingType: 'selfieVsId',
-*     disableFaceMatchAnimation: true,
-*   },
-* });
-*
-* // 3. Subscribe to state changes (optional but recommended)
-* faceMatchManager.subscribe((state) => {
-*   console.log('Face match state:', state.status);
-*   if (state.status === 'finished') {
-*     console.log('Face match complete!', state.matched);
-*   }
-*   if (state.status === 'error') {
-*     console.error('Error:', state.error);
-*   }
-* });
-*
-* // 4. Start the flow
-* faceMatchManager.load();
-*
-* // 5. Auto-completes when disableFaceMatchAnimation is true
-* // Or call faceMatchManager.continue() after animation in custom UI
-*
-* // 6. Clean up when done
-* faceMatchManager.stop();
-* ```
-*
-* @example Headless face match with custom UI
-* ```typescript
-* const faceMatchManager = createFaceMatchManager({
-*   config: { matchingType: 'selfieVsId', disableFaceMatchAnimation: false },
-* });
-*
-* faceMatchManager.subscribe((state) => {
-*   if (state.status === 'animating') {
-*     // Render your custom animation
-*     renderAnimation(state.images, state.result);
-*   }
-*   if (state.status === 'result') {
-*     // Show result and wait for user to click continue
-*     showResult(state.matched);
-*   }
-* });
-*
-* faceMatchManager.load();
-* // When animation completes in your UI:
-* faceMatchManager.animationComplete();
-* // When user clicks continue:
-* faceMatchManager.continue();
-* ```
-*/
-function mapState(snapshot) {
-	const typedSnapshot = snapshot;
-	const { context } = typedSnapshot;
-	if (typedSnapshot.matches("idle")) return { status: "idle" };
-	if (typedSnapshot.matches("loading")) return { status: "loading" };
-	if (typedSnapshot.matches("animating")) return {
-		status: "animating",
-		images: context.images,
-		result: context.result
-	};
-	if (typedSnapshot.matches("result")) return {
-		status: "result",
-		images: context.images,
-		result: context.result,
-		matched: context.result.matched
-	};
-	if (typedSnapshot.matches("finished")) return {
-		status: "finished",
-		matched: context.result?.matched ?? null
-	};
-	if (typedSnapshot.matches("error")) return {
-		status: "error",
-		error: context.error ?? "An error occurred"
-	};
-	return { status: "idle" };
-}
-function createApi({ actor, trackElementClicked }) {
-	return {
-		load() {
-			actor.send({ type: "LOAD" });
-		},
-		animationComplete() {
-			actor.send({ type: "ANIMATION_COMPLETE" });
-		},
-		continue() {
-			trackElementClicked?.("continue");
-			actor.send({ type: "CONTINUE" });
-		},
-		reset() {
-			actor.send({ type: "RESET" });
-		}
-	};
-}
-/**
-* Creates a face match manager for headless or UI-driven usage.
-*
-* The manager provides a state machine-based API for face comparison
-* with optional animation display.
-*
-* @param options - Configuration options
-* @param options.config - Face match configuration
-* @param options.config.matchingType - Which images to compare (default: 'selfieVsId')
-* @param options.config.disableFaceMatchAnimation - Skip animation and auto-complete (default: false)
-*
-* @returns Face match manager with state, API methods, and subscription
-*
-* @example Headless usage
-* ```typescript
-* const manager = createFaceMatchManager({
-*   config: { matchingType: 'selfieVsId', disableFaceMatchAnimation: true },
-* });
-*
-* manager.subscribe((state) => console.log(state.status));
-* manager.load();
-* // Auto-completes when disableFaceMatchAnimation is true
-* manager.stop();
-* ```
-*
-* @example With React/Preact UI hook
-* ```tsx
-* const [state, manager] = useManager(() => createFaceMatchManager({ config }));
-*
-* if (state.status === 'animating') {
-*   return <Animation images={state.images} />;
-* }
-* ```
-*/
-function createFaceMatchManager(options) {
-	return createManager({
-		actor: createFaceMatchActor(options),
-		mapState,
-		createApi,
-		instrumentation: createManagerInstrumentation(eventModuleNames.faceMatch)
-	});
-}
-
-//#endregion
-export { ID_FACE_EXTRACTION_SKIPPED_CODE, createFaceMatchManager, faceMatchMachine, isFaceExtractionSkippedError };
+import { n as ID_FACE_EXTRACTION_SKIPPED_CODE, r as isFaceExtractionSkippedError, t as faceMatchMachine } from "./faceMatchStateMachine-CJiO2yLO.esm.js";
+import { n as createFaceMatchManagerFromActor, t as createFaceMatchManager } from "./faceMatchManager-BXp2WUT-.esm.js";
+export { ID_FACE_EXTRACTION_SKIPPED_CODE, createFaceMatchManager, createFaceMatchManagerFromActor, faceMatchMachine, isFaceExtractionSkippedError };

package/dist/{faceCaptureManagerFactory-C9TiGbkA.esm.js → faceCaptureManagerFactory-4VejGOQX.esm.js}

@@ -1,14 +1,14 @@
-import { n as eventModuleNames, o as topLevelStateName, r as eventScreenNames, s as createManagerInstrumentation } from "./events-1wxZ97yf.esm.js";
-import { l as createManager } from "./xstate.esm-nY3M5UYm.esm.js";
-import { n as concealmentToAvatar } from "./faceCaptureSetup-BqhqfFHL.esm.js";
-import { t as setWasmDsFlagSync } from "./wasmDsFlagSync-Ch0mFJNT.esm.js";
-import { t as BrowserVisibilityObserverProvider } from "./BrowserVisibilityObserverProvider-GBS6XSii.esm.js";
-import { r as primeMotionFromUserGestureIfNeeded } from "./permissionServices-C_kxhNeo.esm.js";
-
+import { n as eventModuleNames, o as createManagerInstrumentation, r as eventScreenNames } from "./events-CxfNJVZW.esm.js";
+import { t as topLevelStateName } from "./topLevelStateName-B5i2avbh.esm.js";
+import { c as createManager } from "./xstate.esm-Cf4e0Cfd.esm.js";
+import { n as concealmentToAvatar } from "./faceCaptureSetup-BB5KEtbV.esm.js";
+import { t as setWasmDsFlagSync } from "./wasmDsFlagSync-BqUCwLY8.esm.js";
+import { t as BrowserVisibilityObserverProvider } from "./BrowserVisibilityObserverProvider-BX1BiLDK.esm.js";
+import { r as primeMotionFromUserGestureIfNeeded } from "./permissionServices-UvUcOSRb.esm.js";
 //#region src/internal/faceCapture/faceCaptureManagerFactory.ts
 function getPermissionStatus(snapshot) {
 	if (!snapshot.matches("permissions")) return;
-	if (snapshot.matches({ permissions: "idle" })) return "idle";
+	if (snapshot.matches({ permissions: "idle" })) return "checking";
 	if (snapshot.matches({ permissions: "waitingForUser" })) return "idle";
 	if (snapshot.matches({ permissions: "learnMore" })) return "learnMore";
 	if (snapshot.matches({ permissions: "requesting" })) return "requesting";
@@ -54,10 +54,10 @@ function mapState(snapshot) {
 			captureStatus: captureStatus ?? "initializing",
 			stream: context.stream,
 			detectionStatus: context.detectionStatus ?? "idle",
-			debugFrame: context.debugFrame,
 			attemptsRemaining: context.attemptsRemaining ?? 0,
 			uploadError: context.uploadError,
 			assistedOnboarding: context.config?.assistedOnboarding ?? false,
+			usingBackCamera: context.usingBackCamera ?? false,
 			ageAssurance: context.config?.ageAssurance === true,
 			onDeviceMode: context.config?.onDeviceFaceResultsSubmissionEnabled === true,
 			obfuscateWithAvatar,
@@ -114,8 +114,6 @@ function getCapturingScreen(detectionStatus) {
 		case "detecting":
 		case "idle":
 		case "offline": return "faceCapture.genericErrors.noConnection";
-		case "success":
-		case "error":
 		default: return "faceCapture.capturing.initiatingState";
 	}
 }
@@ -141,11 +139,6 @@ function getResultErrorScreen(errorCode, attemptsRemaining) {
 		case "SERVER_ERROR":
 		case "PROCESSING_ERROR":
 		case "BAD_REQUEST": return `faceCapture.resultError.processingFailed${exhaustedSuffix}`;
-		case "FACE_NOT_FOUND":
-		case "MULTIPLE_FACES":
-		case "FACE_CROPPING_FAILED":
-		case "FACE_TOO_SMALL":
-		case "LIVENESS_ERROR":
 		default: return `faceCapture.resultError.faceNotAligned${exhaustedSuffix}`;
 	}
 }
@@ -213,11 +206,6 @@ function getAuthFaceScreenName(snapshot) {
 		case "capture": return getAuthFaceCaptureSubstateScreen(snapshot);
 		case "finished": return eventScreenNames.authFaceUploadSuccess;
 		case "error": return eventScreenNames.authFaceUploadFailed;
-		case "idle":
-		case "loading":
-		case "permissions":
-		case "processing":
-		case "closed":
 		default: return eventScreenNames.authFace;
 	}
 }
@@ -244,16 +232,26 @@ function createApi({ actor, trackElementClicked, trackCaptureAttemptFinished })
 	const snapshot = actor.getSnapshot();
 	snapshot.context.dependencies.trackCaptureAttemptFinished = trackCaptureAttemptFinished;
 	return {
+		/**
+		* Starts the face capture flow.
+		* Goes to `tutorial` if showTutorial is true, otherwise to `loading`.
+		* Requires setup() to have been called with a token first.
+		*/
 		load() {
 			const { config } = actor.getSnapshot().context;
 			if (config.ds === true) setWasmDsFlagSync(true);
 			actor.send({ type: "LOAD" });
 		},
+		/**
+		* Advances to the next step.
+		* From `tutorial` → permissions or capture (based on permission status).
+		* From `capture` → finished.
+		*/
 		async nextStep() {
 			trackElementClicked?.("nextStep");
-			const snapshot$1 = actor.getSnapshot();
-			if (snapshot$1.matches("tutorial")) {
-				const { config, permissionResult } = snapshot$1.context;
+			const snapshot = actor.getSnapshot();
+			if (snapshot.matches("tutorial")) {
+				const { config, permissionResult } = snapshot.context;
 				await primeMotionFromUserGestureIfNeeded({
 					ds: config.ds,
 					cameraGranted: permissionResult === "granted"
@@ -261,29 +259,58 @@ function createApi({ actor, trackElementClicked, trackCaptureAttemptFinished })
 			}
 			actor.send({ type: "NEXT_STEP" });
 		},
+		/**
+		* Requests camera permission via getUserMedia.
+		* Only effective when in `permissions.idle` or `permissions.learnMore` state.
+		*/
 		requestPermission() {
 			trackElementClicked?.("requestPermission");
 			actor.send({ type: "REQUEST_PERMISSION" });
 		},
+		/**
+		* Navigates to the "learn more" permission screen.
+		* Only effective when in `permissions.idle` state.
+		*/
 		goToLearnMore() {
 			trackElementClicked?.("goToLearnMore");
 			actor.send({ type: "GO_TO_LEARN_MORE" });
 		},
+		/**
+		* Goes back from "learn more" to the initial permission screen.
+		* Only effective when in `permissions.learnMore` state.
+		*/
 		back() {
 			trackElementClicked?.("back");
 			actor.send({ type: "BACK" });
 		},
+		/**
+		* Closes the face capture flow and transitions to `closed` state.
+		* Can be called from any state.
+		*/
 		close() {
 			trackElementClicked?.("close");
 			actor.send({ type: "QUIT" });
 		},
+		/**
+		* Resets the face capture manager to its initial `idle` state.
+		* Can be called from `error` state. Not available from `finished` (final state).
+		*/
 		reset() {
 			actor.send({ type: "RESET" });
 		},
+		/**
+		* Retries the capture after an upload error.
+		* Only effective when in `capture.uploadError` state and `attemptsRemaining > 0`.
+		* If no attempts remaining, the transition is blocked.
+		*/
 		retryCapture() {
 			trackElementClicked?.("retryCapture");
 			actor.send({ type: "RETRY_CAPTURE" });
 		},
+		/**
+		* Captures a face in manual capture mode.
+		* Only effective when in `capture.detecting` state and `detectionStatus === 'manualCapture'`.
+		*/
 		capture() {
 			trackElementClicked?.("capture");
 			actor.send({ type: "MANUAL_CAPTURE" });
@@ -317,11 +344,6 @@ function getFaceErrorReason(errorCode) {
 		case "SERVER_ERROR":
 		case "PROCESSING_ERROR":
 		case "BAD_REQUEST": return "processingFailed";
-		case "FACE_NOT_FOUND":
-		case "MULTIPLE_FACES":
-		case "FACE_CROPPING_FAILED":
-		case "FACE_TOO_SMALL":
-		case "LIVENESS_ERROR":
 		default: return "faceNotAligned";
 	}
 }
@@ -391,6 +413,5 @@ function createFaceCaptureManagerFromActor(actor, moduleName, visibilityObserver
 		})
 	});
 }
-
 //#endregion
-export { createFaceCaptureManagerFromActor as t };
+export { createFaceCaptureManagerFromActor as t };

package/dist/{faceCaptureManagerFactory-DiJ64oem.d.ts → faceCaptureManagerFactory-BxWPpxyd.d.ts}

@@ -1,24 +1,59 @@
-import { n as StateMachine, t as AnyStateMachine } from "./StateMachine-D5WO6lHS.js";
-import { t as Manager } from "./Manager-goNPc_h_.js";
-import { t as ActorRefFrom } from "./Actor-BwgmOPkb.js";
-import { t as IVisibilityObserverCapability } from "./IVisibilityObserverCapability-BZ1rE7ly.js";
-import { t as CameraStream } from "./camera-CKU96nwJ.js";
-import { t as IncodeCanvas } from "./canvas-90BqS0NF.js";
-import { s as FaceFeed, t as AvatarId, u as FaceCoordinates } from "./createFaceAvatar-CpdYp9Iy.js";
-import { i as FlowModuleConfig } from "./types-BUgeB2X6.js";
-import { n as PermissionStatus, t as PermissionResult } from "./types-BcF-fii5.js";
-import { a as FaceCapturedImageData, i as FaceCaptureOnlyResponse, n as DetectionStatus, o as FaceErrorCode, r as FaceCaptureDependencies, t as BaseFaceCaptureConfig } from "./types-fO6KIdol.js";
-import { t as FaceDetectionProvider } from "./FaceDetectionProvider-CPWg-PAH.js";
-import { t as StreamCanvasCapture } from "./StreamCanvasCapture-DHaWferF.js";
-import { t as DeepsightService } from "./deepsightService-BuTOFTr8.js";
-
+import { A as StateMachine, i as ActorRefFrom, l as AnyStateMachine } from "./spawn-D9jgw9pW.js";
+import "./StateMachine-EDpYWy0i.js";
+import { t as Manager } from "./Manager-CQQ99QOI.js";
+import "./Actor-iTq7YY48.js";
+import { t as IVisibilityObserverCapability } from "./IVisibilityObserverCapability-D4tvIB5v.js";
+import "./index-B8weJxmL.js";
+import { t as CameraStream } from "./camera-9wWD-pwg.js";
+import { o as IncodeCanvas } from "./IStorageCapability-ORkQfK3F.js";
+import { i as FaceData, r as FaceCoordinates, t as FaceDetectionProvider } from "./FaceDetectionProvider-Mh6q3EbA.js";
+import { t as AvatarId } from "./createFaceAvatar-BEj18KXi.js";
+import { i as FlowModuleConfig } from "./types-KPvmag_B.js";
+import { a as FaceCapturedImageData, i as FaceCaptureOnlyResponse, n as DetectionStatus, o as FaceErrorCode, r as FaceCaptureDependencies, t as BaseFaceCaptureConfig } from "./types-Hmd7U0JA.js";
+import { n as PermissionStatus, t as PermissionResult } from "./types-BEwVKkLJ.js";
+import { t as AuthenticationConfig } from "./types-EELWyWpd.js";
+import { n as StreamCanvasCapture, t as DeepsightService } from "./deepsightService-DLVQS_RH.js";
 //#region src/modules/authentication/authenticationStateMachine.d.ts
 declare const _authenticationMachine: AnyStateMachine;
 type AuthenticationMachine = typeof _authenticationMachine;
 declare const authenticationMachine: AnyStateMachine;
 //#endregion
-//#region src/modules/authentication/types.d.ts
-type AuthenticationConfig = FlowModuleConfig['AUTHENTICATION'] & BaseFaceCaptureConfig;
+//#region ../infra/src/avatar/faceFeed.d.ts
+/**
+ * A tiny per-frame pub/sub channel for the Incode WASM pipeline's `FaceData`.
+ *
+ * The parked `incode-2d` avatar drives the cosmetic avatar from the **existing** Incode face-detection
+ * pipeline (no second MediaPipe model). The detection pipeline lives in core's
+ * detection actor, while the avatar lives in the avatar actor — so the avatar is
+ * *fed* `FaceData` through this channel rather than running its own model.
+ *
+ * Deliberately NOT routed through XState events/context: the pipeline emits
+ * ~10×/s, and assigning that into context would re-run `mapState` and notify all
+ * manager subscribers 10×/s — needless churn that could itself regress UI perf.
+ * The feed is a plain emitter passed as input to both actors (detection
+ * publishes, the avatar source subscribes); nothing else observes it.
+ *
+ * Strictly read-only w.r.t. the authoritative pipeline — the feed only forwards
+ * data the pipeline already computed; it never influences detection/autocapture.
+ */
+interface FaceFeedReader {
+  /** Subscribe to per-frame faces. Returns an unsubscribe function. */
+  subscribe(listener: (face: FaceData) => void): () => void;
+  /** The most recently published face, or null if none yet. */
+  getLatest(): FaceData | null;
+  /**
+   * Subscribe to the coarse "eyes closed" pulse — the only real eye signal the
+   * Incode pipeline exposes (a threshold event, both eyes, fired only when the
+   * closed-eyes check is enabled via `validateClosedEyes`). The avatar uses it
+   * to drive a real blink. Returns an unsubscribe function.
+   */
+  onEyesClosed(listener: () => void): () => void;
+}
+interface FaceFeed extends FaceFeedReader {
+  publish(face: FaceData): void;
+  /** Fire the eyes-closed pulse (from the detection pipeline's threshold event). */
+  signalEyesClosed(): void;
+}
 //#endregion
 //#region src/modules/authentication/authenticationActor.d.ts
 type CreateAuthenticationActorOptions = {
@@ -120,9 +155,9 @@ type FaceCaptureContext = {
   stream: CameraStream | undefined;
   provider: FaceDetectionProvider | undefined;
   frameCapturer: StreamCanvasCapture | undefined;
+  usingBackCamera: boolean;
   error: string | FaceErrorObject | undefined;
   detectionStatus: DetectionStatus;
-  debugFrame: ImageData | undefined;
   capturedImage: IncodeCanvas | undefined;
   faceCoordinates: FaceCoordinates | undefined;
   uploadResponse: Record<string, unknown> | undefined;
@@ -182,9 +217,6 @@ type FaceCaptureEvent = {
 } | {
   type: 'DETECTION_UPDATE';
   status: DetectionStatus;
-} | {
-  type: 'DETECTION_FRAME';
-  frame: ImageData;
 } | {
   type: 'DETECTION_SUCCESS';
   canvas: IncodeCanvas;
@@ -275,14 +307,21 @@ type FaceCaptureCaptureState = {
   stream: CameraStream | undefined;
   /** Current face detection status */
   detectionStatus: DetectionStatus;
-  /** Latest frame processed in the detection loop (for UI debug rendering) */
-  debugFrame: ImageData | undefined;
   /** Number of capture attempts remaining */
   attemptsRemaining: number;
   /** Error message from failed upload */
   uploadError: string | undefined;
-  /** Whether assisted onboarding mode is active (back camera, no mirror) */
+  /**
+   * The requested config flag only — it does NOT say which camera is in use,
+   * since devices without a rear camera fall back to the front one. Use
+   * {@link usingBackCamera} for camera-dependent concerns like mirroring.
+   */
   assistedOnboarding: boolean;
+  /**
+   * Whether the active `stream` really came from a rear camera. Mirror the
+   * preview when this is `false` (selfie view), leave it as-is when `true`.
+   */
+  usingBackCamera: boolean;
   ageAssurance?: boolean;
   /**
    * Whether on-device face-results submission is enabled
@@ -397,4 +436,4 @@ declare function createFaceCaptureManagerFromActor(actor: FaceCaptureActor, modu
 };
 type FaceCaptureManager = ReturnType<typeof createFaceCaptureManagerFromActor>;
 //#endregion
-export { authenticationMachine as S, SendFaceImageResponse as _, SelfieCaptureOnlyMachine as a, createAuthenticationActor as b, SelfieActor as c, FaceCaptureContext as d, FaceCaptureEvent as f, SelfieConfig as g, SelfieCaptureOnlyConfig as h, SelfieCaptureOnlyActor as i, SelfieMachine as l, faceCaptureMachine as m, FaceCaptureManagerState as n, selfieCaptureOnlyMachine as o, FaceCaptureInput as p, CreateSelfieCaptureOnlyActorOptions as r, CreateSelfieActorOptions as s, FaceCaptureManager as t, selfieMachine as u, AuthenticationActor as v, AuthenticationConfig as x, CreateAuthenticationActorOptions as y };
+export { SendFaceImageResponse as _, SelfieCaptureOnlyMachine as a, createAuthenticationActor as b, SelfieActor as c, FaceCaptureContext as d, FaceCaptureEvent as f, SelfieConfig as g, SelfieCaptureOnlyConfig as h, SelfieCaptureOnlyActor as i, SelfieMachine as l, faceCaptureMachine as m, FaceCaptureManagerState as n, selfieCaptureOnlyMachine as o, FaceCaptureInput as p, CreateSelfieCaptureOnlyActorOptions as r, CreateSelfieActorOptions as s, FaceCaptureManager as t, selfieMachine as u, AuthenticationActor as v, authenticationMachine as x, CreateAuthenticationActorOptions as y };