@sekyro/web 0.1.0-rc.3 → 0.1.0-rc.5

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @sekyro/web
 
+## 0.1.0-rc.5
+
+### Minor Changes
+
+- a14ac15: Pre-capture building blocks: choose the camera at start, warm the face detector ahead of time, and read the camera state for a "get ready" screen.
+  
+  - **Camera at start.** `handle.start({ facing: "user" | "environment" })` (new `LivenessStartOptions`, `CameraFacing` types) picks the camera for this attempt; `retry()` keeps it and `switchCamera()` still flips it. `start()` with no options behaves as before, and `LivenessCaptureOptions.facing` remains the default. `verification.liveness()` handles pass the option through.
+  - **Detector preload.** `preloadLivenessAssets({ assetBaseUrl?, idle?, respectSaveData? })` downloads and initialises the face detector so the capture starts instantly instead of racing the cold-start deadline. It is idempotent per `assetBaseUrl`, never rejects, and resolves the settled status (`LivenessAssetsStatus`): `'ready'`; `'failed'` (call it again to retry); or `'idle'`, meaning nothing was preloaded (server-side rendering, no camera API, or Data-Saver with `respectSaveData: true`) — start normally. `idle: true` defers the load to browser idle time; a capture that needs the detector meanwhile starts it at once. The preload warms the blaze (MediaPipe) tier only, with a generous 120 s init deadline; captures without a preload keep the existing detector ladder and deadline, unchanged.
+  - **Used automatically.** Every `createLivenessCapture` / `verification.liveness()` capture with the same `assetBaseUrl` reuses the preloaded detector — no extra wiring — and destroying or retrying a capture never frees it. The preload is shared across duplicate copies of `@sekyro/web` on the page.
+  - **Status store.** `getLivenessAssetsStatus(assetBaseUrl?)` and `subscribeLivenessAssets(listener, assetBaseUrl?)` (the `useSyncExternalStore` contract: no emit on subscribe) drive a Start button's loading / retry state.
+  - **Release.** `releaseLivenessAssets(assetBaseUrl?)` frees the warmed detector (or cancels a pending idle load) when the user leaves the flow. Never call it while a capture is mounted.
+  - **Camera probes.** `queryCameraPermission()` and `subscribeCameraPermission(listener)` report `CameraPermissionState` (`'granted' | 'prompt' | 'denied' | 'unknown'`; the subscription emits the current state first, then every change). `hasMultipleCameras()` tells whether a front/back choice makes sense (phones and tablets always; desktops with two or more cameras). All are safe to call during server-side rendering and never throw.
+- 66522c3: The liveness capture now keeps the screen awake while the camera is live.
+  
+  - **Screen Wake Lock.** From `starting` through `gating` and `recording`, the capture holds a Screen Wake Lock so the phone does not dim or lock while the person positions their face. It is released on `captured`, `error` and `destroy()`, taken again on `retry()`, and re-taken automatically when the person returns to the page (browsers drop the lock when a page is hidden).
+  - **On by default, best-effort.** Browsers without the Screen Wake Lock API, or a refused request (page not visible, insecure context, blocked by Permissions-Policy), leave the capture exactly as before — nothing throws and no `error` is emitted.
+  - **Opt out:** `keepScreenAwake: false` on `createLivenessCapture({ … })` / `verification.liveness({ … })` never requests the lock.
+  - **Iframes:** if you embed the capture in an iframe, allow the permission alongside the camera — `<iframe allow="camera; screen-wake-lock">` — and do not send `Permissions-Policy: screen-wake-lock=()`. Without it the capture still works; the screen may just dim.
+  - `@sekyro/react`'s `<LivenessCapture>` gets this automatically once it runs on this `@sekyro/web` version.
+
+## 0.1.0-rc.4
+
+### Minor Changes
+
+- 9991ea5: Face-capture timing on `captured` and on the liveness submission (session insights).
+  
+  - `CapturedArtifacts` gains `engine` (`'v3'`) and three optional whole-millisecond durations measured by the capture engine with `performance.now()`: `cameraReadyMs` (camera request → preview live), `faceAcquireMs` (camera ready → first accepted face) and `captureMs` (first accepted face → gate progress 100 %, i.e. capture complete, before the clip window and any upload; a face lost and re-acquired keeps the first start). The core `CaptureArtifacts` carries the same marks as `timing`.
+  - `createVerification` forwards them, together with the already-known `width` / `height` / `clipMs` and the engine id, as `input.capture` on the `liveness` submission (`LivenessInput.capture`, `LivenessCaptureInput`) so the Sekyro dashboard can show how long the face capture, the upload and the processing of each check took. Nothing else changes on the wire; `face_match` is untouched.
+  - `@sekyro/react`: `<LivenessCapture onCaptured>` receives the new fields unchanged (no code change — the dependency bump only).
+
 ## 0.1.0-rc.3
 
 ### Patch Changes

package/README.md

@@ -31,6 +31,50 @@ under `/models-v3` (or `assetBaseUrl`), and your page origin registered with Sek
 > task (Changesets + Trusted Publishing). Sekyro's own hosted page consumes it via a
 > `file:` link today. Formerly `@ibtikar/identity-web-sdk` (internal).
 
+## Preload & camera probes
+
+Warm the face detector before the user taps Start (on the step before the
+capture, or at mount), and read the camera permission for your "get ready" UI:
+
+```ts
+import { createLivenessCapture, getLivenessAssetsStatus, hasMultipleCameras,
+  preloadLivenessAssets, subscribeCameraPermission, subscribeLivenessAssets } from "@sekyro/web";
+
+void preloadLivenessAssets({ assetBaseUrl: "/models-v3", idle: true }); // never rejects
+const gateStart = (s: string) => (startBtn.disabled = s === "loading");
+gateStart(getLivenessAssetsStatus("/models-v3")); // subscribe does not emit the current status
+subscribeLivenessAssets(gateStart, "/models-v3");
+subscribeCameraPermission((p) => showCameraRow(p)); // granted|prompt|denied|unknown
+const showFacingChoice = await hasMultipleCameras();
+
+const cap = createLivenessCapture({ video, assetBaseUrl: "/models-v3" });
+await cap.start({ facing: "user" }); // reuses the warm detector automatically
+```
+
+- `preloadLivenessAssets` is idempotent per `assetBaseUrl` and resolves the settled
+  status: `'ready'`, `'failed'` (call it again to retry), or `'idle'` — nothing was
+  preloaded (SSR, no camera API, Data-Saver with `respectSaveData`); just start
+  normally. `idle: true` defers the load to browser idle time; a capture that
+  starts meanwhile begins it at once.
+- The preload warms the blaze (MediaPipe) tier with a generous deadline. Every
+  capture created afterwards with the same `assetBaseUrl` uses it without any extra
+  wiring, and destroying a capture never frees it; call
+  `releaseLivenessAssets(assetBaseUrl)` when the user leaves the flow (never while a
+  capture is mounted). Without a preload the capture loads the detector itself, as
+  before.
+- `getLivenessAssetsStatus` / `subscribeLivenessAssets` follow the
+  `useSyncExternalStore` contract (no emit on subscribe). `subscribeCameraPermission`
+  emits the current state first, then every change; `queryCameraPermission` is the
+  one-shot read. Both report `'unknown'` where the Permissions API cannot tell.
+- `start({ facing })` picks the camera for this attempt and its retries;
+  `switchCamera()` still flips it mid-capture.
+- `keepScreenAwake` (capture option, default `true`) holds a Screen Wake Lock while
+  the camera is live (`starting` / `gating` / `recording`), released on `captured`,
+  `error` and `destroy()`, re-taken on `retry()` and when the page is visible again.
+  Best-effort — unsupported or refused requests never affect the capture. In an
+  iframe, allow it: `<iframe allow="camera; screen-wake-lock">`. Pass `false` to
+  never request it.
+
 ## Entry points
 
 | Export | Contents | Public API |

package/dist/{capture-session-v3-CvIfcwST.d.ts → capture-session-v3-Okq0EQHG.d.ts}

@@ -105,6 +105,23 @@ interface GateChecks {
     goodQuality: boolean;
     stable: boolean;
 }
+/**
+ * Client-side capture timing (face-capture duration, 2026-10-17), measured
+ * by the engine with its monotonic clock (`performance.now()` by default) and
+ * rounded to whole milliseconds. All fields are optional: a phase that never
+ * happened (e.g. no face ever detected before a retry) is simply absent.
+ */
+interface CaptureTiming {
+    /** `getUserMedia` call → stream attached and the preview playing. */
+    cameraReadyMs?: number;
+    /** Camera ready → the first tick on which the GATE accepted the face
+     *  (present + size / centering / quality good enough to make progress —
+     *  not merely detected). */
+    faceAcquireMs?: number;
+    /** FIRST accepted face → gate progress 100 % (capture complete, BEFORE the
+     *  clip window / upload). A face lost and re-acquired keeps the first start. */
+    captureMs?: number;
+}
 /** Capture output. Upload is NOT the engine's job — hosts submit these themselves. */
 interface CaptureArtifacts {
     /** Absent in photo mode. */
@@ -115,6 +132,8 @@ interface CaptureArtifacts {
     keyframe: Blob;
     /** JPEG data URL of the keyframe canvas (v1 preview, quality 0.92). */
     previewDataUrl: string;
+    /** Capture-phase timing of the attempt that produced these artifacts. */
+    timing?: CaptureTiming;
 }
 interface CaptureSessionEvents {
     statechange: {
@@ -218,6 +237,10 @@ interface V3GateTick {
     guidanceKey: string;
     /** Fire signal: p ≥ 1 AND no second bad tick (q < Q_GOOD) in READY_WINDOW_MS. */
     ready: boolean;
+    /** The face on THIS tick is ACCEPTED by the gate — present and every factor
+     *  (size, centering, pose, sharpness, exposure, motion) good enough that the
+     *  integrator RISES (q ≥ Q_GOOD). The engine's "first accepted face" mark. */
+    accepted: boolean;
 }
 declare class FaceGateV3 {
     private readonly t;
@@ -406,6 +429,11 @@ interface CaptureSessionV3Options {
     now?: () => number;
 }
 type Handler<K extends keyof CaptureSessionV3Events> = (payload: CaptureSessionV3Events[K]) => void;
+/** Per-start options (the public handle's `start({ facing })`). */
+interface CaptureSessionV3StartOptions {
+    /** Camera for this attempt AND later retries; absent → keep the current one. */
+    facingMode?: "user" | "environment";
+}
 declare class CaptureSessionV3 {
     private readonly options;
     private readonly handlers;
@@ -419,6 +447,10 @@ declare class CaptureSessionV3 {
     private profiler;
     private lastGuidanceKey;
     private positioningStartedAt;
+    private cameraRequestedAt;
+    private cameraReadyAt;
+    private faceAcquiredAt;
+    private captureCompleteAt;
     private fired;
     private carriedDegrade;
     private carriedMeans;
@@ -426,7 +458,9 @@ declare class CaptureSessionV3 {
     get state(): CaptureState;
     on<K extends keyof CaptureSessionV3Events>(event: K, handler: Handler<K>): () => void;
     private emit;
-    start(): Promise<void>;
+    start(options?: CaptureSessionV3StartOptions): Promise<void>;
+    /** The camera the current/next attempt requests (start option, switchCamera toggles). */
+    get facingMode(): "user" | "environment";
     /** Full reset + camera restart — the documented recovery path (v1 parity). */
     retry(): void;
     switchCamera(): void;
@@ -441,6 +475,8 @@ declare class CaptureSessionV3 {
      *  sharpest wins (reuses frame-quality.sharpness via the capture seam). */
     private collectKeyframes;
     private finishCapture;
+    /** The attempt's capture-phase timing (whole ms, ≥ 0); undefined when no mark landed. */
+    private captureTiming;
     private defaultKeyframe;
     /** Reused downscale canvas — falls back to the raw video where canvas 2D
      *  is unavailable (jsdom) so tests and exotic hosts keep detecting. */
@@ -455,4 +491,4 @@ declare class CaptureSessionV3 {
     private now;
 }
 
-export { V3_GATE_DEFAULTS as A, VIDEO_BPS as B, type CameraErrorKind as C, DEFAULT_CLIP_MIME as D, type EscalationClipArtifact as E, FaceGateV3 as F, type GateChecks as G, buildLivenessV2FormData as H, cameraPreflight as I, classifyDevice as J, KEYFRAME_CANDIDATES as K, extForMime as L, MAX_CLIP_BYTES as M, isClipTooLarge as N, isMediaRecorderSupported as O, mapGetUserMediaError as P, pickMimeType as Q, probeDevice as R, STOP_GRACE_MS as S, TIMESLICE_MS as T, type V3ChecksPayload as V, CLIP_MS as a, type CaptureArtifacts as b, type CaptureErrorKind as c, type CaptureSessionEvents as d, CaptureSessionV3 as e, type CaptureSessionV3Events as f, type CaptureSessionV3Options as g, type CaptureState as h, ClipError as i, type ClipErrorKind as j, ClipRecorder as k, type ClipResult as l, DEVICE_PROFILES as m, type DeviceClass as n, type DeviceProbe as o, type DeviceProfile as p, DeviceProfiler as q, type EscalationHook as r, KEYFRAME_WINDOW_MS as s, MIME_CANDIDATES as t, type V3GateFactor as u, type V3GateQuality as v, type V3GateThresholds as w, type V3GateTick as x, type V3GateTickInput as y, type V3TelemetryEvent as z };
+export { type V3GateTickInput as A, type V3TelemetryEvent as B, type CameraErrorKind as C, DEFAULT_CLIP_MIME as D, type EscalationClipArtifact as E, FaceGateV3 as F, type GateChecks as G, V3_GATE_DEFAULTS as H, VIDEO_BPS as I, buildLivenessV2FormData as J, KEYFRAME_CANDIDATES as K, cameraPreflight as L, MAX_CLIP_BYTES as M, classifyDevice as N, extForMime as O, isClipTooLarge as P, isMediaRecorderSupported as Q, mapGetUserMediaError as R, STOP_GRACE_MS as S, TIMESLICE_MS as T, pickMimeType as U, type V3ChecksPayload as V, probeDevice as W, CLIP_MS as a, type CaptureArtifacts as b, type CaptureErrorKind as c, type CaptureSessionEvents as d, CaptureSessionV3 as e, type CaptureSessionV3Events as f, type CaptureSessionV3Options as g, type CaptureSessionV3StartOptions as h, type CaptureState as i, type CaptureTiming as j, ClipError as k, type ClipErrorKind as l, ClipRecorder as m, type ClipResult as n, DEVICE_PROFILES as o, type DeviceClass as p, type DeviceProbe as q, type DeviceProfile as r, DeviceProfiler as s, type EscalationHook as t, KEYFRAME_WINDOW_MS as u, MIME_CANDIDATES as v, type V3GateFactor as w, type V3GateQuality as x, type V3GateThresholds as y, type V3GateTick as z };

package/dist/{capture-session-v3-COIO_F2w.d.cts → capture-session-v3-UQU_WjO2.d.cts}

@@ -105,6 +105,23 @@ interface GateChecks {
     goodQuality: boolean;
     stable: boolean;
 }
+/**
+ * Client-side capture timing (face-capture duration, 2026-10-17), measured
+ * by the engine with its monotonic clock (`performance.now()` by default) and
+ * rounded to whole milliseconds. All fields are optional: a phase that never
+ * happened (e.g. no face ever detected before a retry) is simply absent.
+ */
+interface CaptureTiming {
+    /** `getUserMedia` call → stream attached and the preview playing. */
+    cameraReadyMs?: number;
+    /** Camera ready → the first tick on which the GATE accepted the face
+     *  (present + size / centering / quality good enough to make progress —
+     *  not merely detected). */
+    faceAcquireMs?: number;
+    /** FIRST accepted face → gate progress 100 % (capture complete, BEFORE the
+     *  clip window / upload). A face lost and re-acquired keeps the first start. */
+    captureMs?: number;
+}
 /** Capture output. Upload is NOT the engine's job — hosts submit these themselves. */
 interface CaptureArtifacts {
     /** Absent in photo mode. */
@@ -115,6 +132,8 @@ interface CaptureArtifacts {
     keyframe: Blob;
     /** JPEG data URL of the keyframe canvas (v1 preview, quality 0.92). */
     previewDataUrl: string;
+    /** Capture-phase timing of the attempt that produced these artifacts. */
+    timing?: CaptureTiming;
 }
 interface CaptureSessionEvents {
     statechange: {
@@ -218,6 +237,10 @@ interface V3GateTick {
     guidanceKey: string;
     /** Fire signal: p ≥ 1 AND no second bad tick (q < Q_GOOD) in READY_WINDOW_MS. */
     ready: boolean;
+    /** The face on THIS tick is ACCEPTED by the gate — present and every factor
+     *  (size, centering, pose, sharpness, exposure, motion) good enough that the
+     *  integrator RISES (q ≥ Q_GOOD). The engine's "first accepted face" mark. */
+    accepted: boolean;
 }
 declare class FaceGateV3 {
     private readonly t;
@@ -406,6 +429,11 @@ interface CaptureSessionV3Options {
     now?: () => number;
 }
 type Handler<K extends keyof CaptureSessionV3Events> = (payload: CaptureSessionV3Events[K]) => void;
+/** Per-start options (the public handle's `start({ facing })`). */
+interface CaptureSessionV3StartOptions {
+    /** Camera for this attempt AND later retries; absent → keep the current one. */
+    facingMode?: "user" | "environment";
+}
 declare class CaptureSessionV3 {
     private readonly options;
     private readonly handlers;
@@ -419,6 +447,10 @@ declare class CaptureSessionV3 {
     private profiler;
     private lastGuidanceKey;
     private positioningStartedAt;
+    private cameraRequestedAt;
+    private cameraReadyAt;
+    private faceAcquiredAt;
+    private captureCompleteAt;
     private fired;
     private carriedDegrade;
     private carriedMeans;
@@ -426,7 +458,9 @@ declare class CaptureSessionV3 {
     get state(): CaptureState;
     on<K extends keyof CaptureSessionV3Events>(event: K, handler: Handler<K>): () => void;
     private emit;
-    start(): Promise<void>;
+    start(options?: CaptureSessionV3StartOptions): Promise<void>;
+    /** The camera the current/next attempt requests (start option, switchCamera toggles). */
+    get facingMode(): "user" | "environment";
     /** Full reset + camera restart — the documented recovery path (v1 parity). */
     retry(): void;
     switchCamera(): void;
@@ -441,6 +475,8 @@ declare class CaptureSessionV3 {
      *  sharpest wins (reuses frame-quality.sharpness via the capture seam). */
     private collectKeyframes;
     private finishCapture;
+    /** The attempt's capture-phase timing (whole ms, ≥ 0); undefined when no mark landed. */
+    private captureTiming;
     private defaultKeyframe;
     /** Reused downscale canvas — falls back to the raw video where canvas 2D
      *  is unavailable (jsdom) so tests and exotic hosts keep detecting. */
@@ -455,4 +491,4 @@ declare class CaptureSessionV3 {
     private now;
 }
 
-export { V3_GATE_DEFAULTS as A, VIDEO_BPS as B, type CameraErrorKind as C, DEFAULT_CLIP_MIME as D, type EscalationClipArtifact as E, FaceGateV3 as F, type GateChecks as G, buildLivenessV2FormData as H, cameraPreflight as I, classifyDevice as J, KEYFRAME_CANDIDATES as K, extForMime as L, MAX_CLIP_BYTES as M, isClipTooLarge as N, isMediaRecorderSupported as O, mapGetUserMediaError as P, pickMimeType as Q, probeDevice as R, STOP_GRACE_MS as S, TIMESLICE_MS as T, type V3ChecksPayload as V, CLIP_MS as a, type CaptureArtifacts as b, type CaptureErrorKind as c, type CaptureSessionEvents as d, CaptureSessionV3 as e, type CaptureSessionV3Events as f, type CaptureSessionV3Options as g, type CaptureState as h, ClipError as i, type ClipErrorKind as j, ClipRecorder as k, type ClipResult as l, DEVICE_PROFILES as m, type DeviceClass as n, type DeviceProbe as o, type DeviceProfile as p, DeviceProfiler as q, type EscalationHook as r, KEYFRAME_WINDOW_MS as s, MIME_CANDIDATES as t, type V3GateFactor as u, type V3GateQuality as v, type V3GateThresholds as w, type V3GateTick as x, type V3GateTickInput as y, type V3TelemetryEvent as z };
+export { type V3GateTickInput as A, type V3TelemetryEvent as B, type CameraErrorKind as C, DEFAULT_CLIP_MIME as D, type EscalationClipArtifact as E, FaceGateV3 as F, type GateChecks as G, V3_GATE_DEFAULTS as H, VIDEO_BPS as I, buildLivenessV2FormData as J, KEYFRAME_CANDIDATES as K, cameraPreflight as L, MAX_CLIP_BYTES as M, classifyDevice as N, extForMime as O, isClipTooLarge as P, isMediaRecorderSupported as Q, mapGetUserMediaError as R, STOP_GRACE_MS as S, TIMESLICE_MS as T, pickMimeType as U, type V3ChecksPayload as V, probeDevice as W, CLIP_MS as a, type CaptureArtifacts as b, type CaptureErrorKind as c, type CaptureSessionEvents as d, CaptureSessionV3 as e, type CaptureSessionV3Events as f, type CaptureSessionV3Options as g, type CaptureSessionV3StartOptions as h, type CaptureState as i, type CaptureTiming as j, ClipError as k, type ClipErrorKind as l, ClipRecorder as m, type ClipResult as n, DEVICE_PROFILES as o, type DeviceClass as p, type DeviceProbe as q, type DeviceProfile as r, DeviceProfiler as s, type EscalationHook as t, KEYFRAME_WINDOW_MS as u, MIME_CANDIDATES as v, type V3GateFactor as w, type V3GateQuality as x, type V3GateThresholds as y, type V3GateTick as z };