@simprints/simface-sdk 0.6.1 → 0.7.1

package/README.md

@@ -8,7 +8,7 @@ This repository is the public frontend SDK and demo repo for SimFace. For fronte
 
 The backend API, infrastructure, and TensorFlow Lite runtime live in the separate private backend repository.
 
-In standard browsers, the SDK uses an in-page camera flow powered by `getUserMedia()`. In WhatsApp, it falls back to the native capture handoff because that path is more reliable in the in-app browser.
+The capture flow is planned explicitly as: auto camera -> manual camera -> media picker. Hosts can keep the default popup experience or opt into embedded capture with the same fallback policy.
 
 ## Quick Start
 
@@ -90,12 +90,41 @@ npm run dev
 
 The demo runs at `http://localhost:4173` and consumes the built SDK artifact from `dist/`.
 
+## Capture strategy
+
+The top-level SDK helpers accept an optional third `captureOptions` argument so the host can choose popup vs embedded capture and tune the fallback chain:
+
+```javascript
+import { enroll } from '@simprints/simface-sdk';
+
+const result = await enroll(config, 'unique-user-id', {
+  presentation: 'embedded',
+  container: '#capture-slot',
+  capturePreference: 'auto-preferred',
+  allowMediaPickerFallback: true,
+  label: 'Capture a face for enrollment',
+  confirmLabel: 'Confirm enrollment capture',
+});
+```
+
+Supported capture planning options:
+
+- `presentation: 'popup' | 'embedded'`
+- `capturePreference: 'auto-preferred' | 'manual-only'`
+- `allowMediaPickerFallback: boolean`
+- `container: HTMLElement | string` (required for top-level embedded capture)
+- `label` / `confirmLabel`
+
 ## Web Component
 
 For more control over the UI, use the `<simface-capture>` Web Component directly:
 
 ```html
-<simface-capture label="Take a selfie for verification"></simface-capture>
+<simface-capture
+  embedded
+  capture-preference="auto-preferred"
+  label="Take a selfie for verification"
+></simface-capture>
 
 <script type="module">
   import '@simprints/simface-sdk';
@@ -129,6 +158,10 @@ For more control over the UI, use the `<simface-capture>` Web Component directly
 | Attribute | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `label` | String | `"Take a selfie"` | Instructional text shown on the capture button |
+| `embedded` | Boolean | `false` | Runs the component inline instead of delegating to the popup capture service |
+| `confirm-label` | String | `"Use this capture"` | Confirm button label used in preview state |
+| `capture-preference` | `"auto-preferred" \| "manual-only"` | `"auto-preferred"` | Whether auto capture should be preferred or disabled |
+| `allow-media-picker-fallback` | Boolean | `true` | Whether the component may fall back to the media picker if camera capture is unavailable |
 
 ### Events
 
@@ -140,7 +173,7 @@ For more control over the UI, use the `<simface-capture>` Web Component directly
 
 ## API Reference
 
-### `enroll(config, clientId): Promise<EnrollResult>`
+### `enroll(config, clientId, captureOptions?): Promise<EnrollResult>`
 
 Opens the camera, captures a face image with quality validation, and enrolls the user.
 
@@ -150,6 +183,7 @@ Parameters:
 |-----------|------|-------------|
 | `config` | `SimFaceConfig` | SDK configuration (`apiUrl`, `projectId`, `apiKey`) |
 | `clientId` | `string` | Unique identifier for the user |
+| `captureOptions` | `SimFaceCaptureOptions` | Optional capture presentation/fallback overrides |
 
 Returns `EnrollResult`:
 ```typescript
@@ -161,7 +195,7 @@ Returns `EnrollResult`:
 }
 ```
 
-### `verify(config, clientId): Promise<VerifyResult>`
+### `verify(config, clientId, captureOptions?): Promise<VerifyResult>`
 
 Opens the camera, captures a face image, and verifies against the enrolled face.
 
@@ -171,6 +205,7 @@ Parameters:
 |-----------|------|-------------|
 | `config` | `SimFaceConfig` | SDK configuration (`apiUrl`, `projectId`, `apiKey`) |
 | `clientId` | `string` | Unique identifier for the user |
+| `captureOptions` | `SimFaceCaptureOptions` | Optional capture presentation/fallback overrides |
 
 Returns `VerifyResult`:
 ```typescript
@@ -193,6 +228,19 @@ Returns `VerifyResult`:
 }
 ```
 
+### `SimFaceCaptureOptions`
+
+```typescript
+{
+  presentation?: 'popup' | 'embedded';
+  capturePreference?: 'auto-preferred' | 'manual-only';
+  allowMediaPickerFallback?: boolean;
+  container?: HTMLElement | string;
+  label?: string;
+  confirmLabel?: string;
+}
+```
+
 ## Backend API Endpoints
 
 For clients integrating directly with the REST API:

package/dist/components/simface-capture.d.ts

@@ -1,4 +1,5 @@
 import { LitElement } from 'lit';
+import type { CapturePreference } from '../types/index.js';
 /**
  * <simface-capture> — Web Component for capturing and quality-checking face images.
  *
@@ -12,6 +13,8 @@ export declare class SimFaceCapture extends LitElement {
     embedded: boolean;
     active: boolean;
     confirmLabel: string;
+    capturePreference: CapturePreference;
+    allowMediaPickerFallback: boolean;
     private captureState;
     private errorMessage;
     private feedbackMessage;
@@ -19,16 +22,13 @@ export declare class SimFaceCapture extends LitElement {
     private previewUrl;
     private countdownProgress;
     private qualityResult;
+    private canTakePhoto;
     private embeddedVideoElement?;
     private stream;
-    private animationFrameId;
-    private analysisInFlight;
-    private lastAnalysisTimestamp;
+    private sessionController;
+    private currentCaptureStep;
     private capturedBlob;
-    private countdownStartedAt;
-    private bestCaptureBlob;
-    private bestCaptureScore;
-    private bestQualityResult;
+    private pendingActiveSync;
     static styles: import("lit").CSSResult;
     disconnectedCallback(): void;
     updated(changedProperties: Map<string, unknown>): void;
@@ -39,28 +39,26 @@ export declare class SimFaceCapture extends LitElement {
     private handlePopupCapture;
     private handlePopupRetake;
     private handlePopupCancel;
-    private startEmbeddedCapture;
-    private scheduleEmbeddedAnalysis;
-    private captureEmbeddedFrame;
-    private considerBestFrame;
-    private finishCountdownCapture;
-    private assessCapturedBlob;
+    private beginEmbeddedCapture;
+    private startEmbeddedMediaPicker;
+    private applySessionState;
+    private showPickedPreview;
     private handleEmbeddedManualCapture;
     private handleEmbeddedRetake;
     private handleEmbeddedConfirm;
     private handleEmbeddedCancel;
     private handleEmbeddedError;
+    private endEmbeddedCapture;
     private stopEmbeddedSession;
     private resetEmbeddedState;
     private resetPopupState;
+    private setPreviewBlob;
+    private clearPreviewUrl;
     private dispatchCaptured;
     private dispatchCancelled;
     private dispatchError;
     private feedbackClass;
-    private waitForVideoReady;
-    private captureVideoFrame;
-    private resumeEmbeddedVideo;
-    private resetCountdown;
+    private assessPickedBlob;
 }
 declare global {
     interface HTMLElementTagNameMap {