@daboss2003/liveness-web 1.0.7 → 1.0.8

package/README.md

@@ -104,6 +104,60 @@ cd demo-apps/web && npm install && npm run dev
 
 All new options are optional — omitting them gives you the original full-screen oval behaviour.
 
+## Picking which challenges run
+
+By default, all 5 challenges run in a random order. Pass `steps` to restrict to a subset (e.g. for shorter flows or A/B testing). The dot progress indicator and the progress ring both adjust to the active subset count.
+
+```ts
+import { startLiveness, type LivenessStepKey } from "@daboss2003/liveness-web";
+
+startLiveness({
+  steps: ["nod", "blink", "mouth"],   // run only these, in this set
+  shuffleSteps: true,                 // default true — randomise within the subset
+  callbacks: { /* … */ },
+});
+```
+
+Valid keys are `"left"`, `"blink"`, `"right"`, `"nod"`, `"mouth"`. Unknown keys and duplicates are dropped; an empty array falls back to all 5.
+
+`shuffleSteps: false` runs the steps in the order you pass.
+
+## Tuning individual steps
+
+Each challenge has its own thresholds — bump them up to be stricter (harder to pass, fewer false positives), or down to be more lenient.
+
+**Blink**
+
+| Field | Default | Effect |
+|---|---|---|
+| `blinkClosedThreshold` | `0.50` | Min blendshape score that counts as "eyes closed". Raise to reject squinting / glare / hooded eyelids; lower if real blinks don't register. Below ~0.35 you start catching passive eye states. |
+| `blinkOpenThreshold`   | `0.25` | Max score that counts as "eyes open". Keep a clear gap from `blinkClosedThreshold`. |
+| `blinkMinClosedMs`     | `60`   | Eyes must stay closed at least this long. Raise to require deliberate (slower) blinks. |
+| `blinkMaxDurationMs`   | `4000` | Abandon and reset if eyes stay closed longer than this. |
+
+**Head turn** — `yawTurnDelta` (degrees needed), `yawWrongDirDelta` (wrong-direction abort), `headTurnHoldMs` (sustain time).
+
+**Nod** — `nodDownDelta` (degrees chin must drop), `nodReturnFraction`, `nodReturnMaxDelta`.
+
+**Mouth** — `mouthOpenThreshold`, `mouthOpenMarThreshold`, `mouthHoldMs`.
+
+**Capture (post-success)** — `captureMaxYaw`, `captureMaxPitch`, `captureMaxMouthScore`, `captureMaxBlinkScore` (all bound how "neutral" the final frame must be).
+
+Pass any subset as part of `config`:
+
+```ts
+startLiveness({
+  config: {
+    blinkClosedThreshold: 0.55,   // tighter blink
+    blinkMinClosedMs:     100,    // require ~6 frames of closure
+    yawTurnDelta:         12,     // looser head turn
+  },
+  callbacks: { /* … */ },
+});
+```
+
+See [`engine.ts`](src/engine.ts) for the full config object and every default value.
+
 ## Notes
 
 - Uses MediaPipe Tasks Vision Web from CDN.

package/dist/engine.d.ts

@@ -26,7 +26,13 @@ export type LivenessOptions = {
     wasmUrl?: string;
     callbacks?: LivenessCallbacks;
     sounds?: LivenessSoundOptions;
+    /** Subset of challenges to run. Default: all 5. Empty array, duplicates and unknown keys fall back to all 5. */
+    steps?: LivenessStepKey[];
+    /** Shuffle the selected step order. Default true. */
+    shuffleSteps?: boolean;
 };
+/** Identifier for a liveness challenge step. Lowercase, matches the sound-key form. */
+export type LivenessStepKey = "left" | "blink" | "right" | "nod" | "mouth";
 export declare const DEFAULT_MODEL_URL = "https://storage.googleapis.com/mediapipe-models/face_landmarker/face_landmarker/float16/1/face_landmarker.task";
 export declare const DEFAULT_WASM_URL = "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm";
 /** Error code when CDN/assets are unavailable after retries (internet confirmed). */
@@ -50,7 +56,11 @@ export type Metrics = {
     faceCy: number;
     faceSize: number;
 };
-export declare const LIVENESS_STEP_COUNT: 5;
+/** Resolve a caller-supplied step-key array into the corresponding display labels.
+ *  Empty / undefined / all-invalid → default to all 5 steps. Duplicates are dropped. */
+export declare function resolveStepLabels(keys?: readonly LivenessStepKey[] | null): string[];
+/** Default step count (5). The active session may have fewer if `options.steps` is set. */
+export declare const LIVENESS_STEP_COUNT: number;
 export declare class LivenessEngine {
     private opts;
     private landmarker;
@@ -65,6 +75,7 @@ export declare class LivenessEngine {
     private baselineSamples;
     private blinkState;
     private blinkCloseTs;
+    private blinkSeenOpen;
     private nodState;
     private holdStart;
     private latestMetrics;
@@ -84,6 +95,8 @@ export declare class LivenessEngine {
     private clearSessionTimeout;
     private playGoodSound;
     private playCaptureSound;
+    /** Number of challenge steps in the active session (after applying `options.steps`). */
+    get stepCount(): number;
     start(): Promise<void>;
     stop(): void;
     private stopDetectionOnly;

package/dist/engine.js

@@ -61,21 +61,35 @@ function isRetriableCdnError(error) {
         return true;
     return false;
 }
-const STEP_LABELS = [
-    "Turn your head LEFT",
-    "Blink",
-    "Turn your head RIGHT",
-    "Nod your head",
-    "Open your mouth",
+/** Canonical step ordering. Each entry pairs the sound/identifier key with its display label. */
+const STEP_DEFS = [
+    { key: "left", label: "Turn your head LEFT" },
+    { key: "blink", label: "Blink" },
+    { key: "right", label: "Turn your head RIGHT" },
+    { key: "nod", label: "Nod your head" },
+    { key: "mouth", label: "Open your mouth" },
 ];
+const STEP_LABELS = STEP_DEFS.map(s => s.label);
+const STEP_KEY_TO_LABEL = STEP_DEFS.reduce((acc, s) => { acc[s.key] = s.label; return acc; }, {});
 /** Step label → sound key (filename without .mp3). Used so the correct sound plays regardless of randomized step order. */
-const STEP_LABEL_TO_SOUND = {
-    "Turn your head LEFT": "left",
-    "Blink": "blink",
-    "Turn your head RIGHT": "right",
-    "Nod your head": "nod",
-    "Open your mouth": "mouth",
-};
+const STEP_LABEL_TO_SOUND = STEP_DEFS.reduce((acc, s) => { acc[s.label] = s.key; return acc; }, {});
+/** Resolve a caller-supplied step-key array into the corresponding display labels.
+ *  Empty / undefined / all-invalid → default to all 5 steps. Duplicates are dropped. */
+export function resolveStepLabels(keys) {
+    if (!keys || keys.length === 0)
+        return [...STEP_LABELS];
+    const seen = new Set();
+    const out = [];
+    for (const k of keys) {
+        const normalised = (typeof k === "string" ? k.toLowerCase() : "");
+        const label = STEP_KEY_TO_LABEL[normalised];
+        if (label && !seen.has(label)) {
+            seen.add(label);
+            out.push(label);
+        }
+    }
+    return out.length > 0 ? out : [...STEP_LABELS];
+}
 function shuffleArray(array) {
     const out = [...array];
     for (let i = out.length - 1; i > 0; i--) {
@@ -84,6 +98,7 @@ function shuffleArray(array) {
     }
     return out;
 }
+/** Default step count (5). The active session may have fewer if `options.steps` is set. */
 export const LIVENESS_STEP_COUNT = STEP_LABELS.length;
 // ─────────────────────────────────────────────────────────────────────────────
 //  KEY DESIGN: RELATIVE MEASUREMENT
@@ -118,10 +133,13 @@ const config = {
     nodReturnMaxDelta: 12, // cap: never require returning past 12° from baseline
     maxYawDuringNod: 40,
     // ── Blink ──────────────────────────────────────────────────────────────────
-    blinkClosedThreshold: 0.30, // blendshape score = eyes closed
-    blinkOpenThreshold: 0.25, // blendshape score = eyes open
+    // Real blinks easily hit 0.7+. Sustained squinting / glare / hooded eyelids hover at 0.25–0.40 —
+    // keep the "closed" threshold well above that band so passive eye states don't latch CLOSED.
+    blinkClosedThreshold: 0.50,
+    blinkOpenThreshold: 0.25,
     earClosedThreshold: 0.20,
     earOpenThreshold: 0.25,
+    blinkMinClosedMs: 60, // eyes must be CLOSED for at least this long — filters out single-frame noise
     blinkMaxDurationMs: 4000,
     maxYawDuringBlink: 30,
     maxPitchDuringBlink: 30,
@@ -167,6 +185,7 @@ export class LivenessEngine {
         // ── Per-step sub-state ─────────────────────────────────────────────────────
         this.blinkState = "waitingClose";
         this.blinkCloseTs = 0;
+        this.blinkSeenOpen = false; // gate: must observe at least one isEyeOpen frame before allowing a `closed` transition
         this.nodState = "neutral";
         this.holdStart = null;
         this.latestMetrics = null;
@@ -258,10 +277,16 @@ export class LivenessEngine {
             onEnded?.();
     }
     // ── Public ─────────────────────────────────────────────────────────────────
+    /** Number of challenge steps in the active session (after applying `options.steps`). */
+    get stepCount() {
+        return this.steps.length > 0 ? this.steps.length : resolveStepLabels(this.opts.steps).length;
+    }
     async start() {
         this.stopDetectionOnly();
         this.running = true;
-        this.steps = shuffleArray(STEP_LABELS).map((label, index) => ({ index, label }));
+        const selected = resolveStepLabels(this.opts.steps);
+        const ordered = this.opts.shuffleSteps === false ? selected : shuffleArray(selected);
+        this.steps = ordered.map((label, index) => ({ index, label }));
         this.stepIndex = 0;
         this.lastDetectTs = -1;
         this.lastOvalState = null;
@@ -411,6 +436,7 @@ export class LivenessEngine {
     resetStepState() {
         this.blinkState = "waitingClose";
         this.blinkCloseTs = 0;
+        this.blinkSeenOpen = false;
         this.nodState = "neutral";
         this.holdStart = null;
         this.baselineYaw = null;
@@ -472,13 +498,20 @@ export class LivenessEngine {
                 const isEyeOpen = metrics.blinkScore > 0
                     ? metrics.blinkScore < config.blinkOpenThreshold
                     : metrics.ear > config.earOpenThreshold;
-                if (this.blinkState === "waitingClose" && isEyeClosed) {
+                // Confirm eyes were OPEN before we count any closed → open transition.
+                // Kills the "step starts mid-blink / mid-squint" false positive.
+                if (isEyeOpen)
+                    this.blinkSeenOpen = true;
+                if (this.blinkState === "waitingClose" && isEyeClosed && this.blinkSeenOpen) {
                     this.blinkState = "closed";
                     this.blinkCloseTs = now;
                 }
                 else if (this.blinkState === "closed" && isEyeOpen) {
-                    if (now - this.blinkCloseTs <= config.blinkMaxDurationMs)
+                    const dt = now - this.blinkCloseTs;
+                    if (dt >= config.blinkMinClosedMs && dt <= config.blinkMaxDurationMs)
                         return this.advanceStep(now);
+                    // Closed phase too short (noise) or too long (eyes never reopened in time) — discard, wait for next attempt.
+                    // blinkSeenOpen stays true — we've already confirmed the user can open their eyes.
                     this.blinkState = "waitingClose";
                 }
                 break;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { LivenessEngine } from "./engine";
 export type { StartLivenessOptions, LivenessTheme } from "./ui";
-export { DEFAULT_MODEL_URL, DEFAULT_WASM_URL, LIVENESS_ERROR_CDN_NOT_AVAILABLE, LIVENESS_ERROR_OFFLINE, LIVENESS_STEP_COUNT, isCdnNotAvailableError, isOfflineError, LivenessError, } from "./engine";
-export type { LivenessCallbacks, LivenessOptions, LivenessSoundOptions } from "./engine";
+export { DEFAULT_MODEL_URL, DEFAULT_WASM_URL, LIVENESS_ERROR_CDN_NOT_AVAILABLE, LIVENESS_ERROR_OFFLINE, LIVENESS_STEP_COUNT, isCdnNotAvailableError, isOfflineError, resolveStepLabels, LivenessError, } from "./engine";
+export type { LivenessCallbacks, LivenessOptions, LivenessSoundOptions, LivenessStepKey } from "./engine";
 export type { LivenessEngine } from "./engine";
 /**
  * Starts liveness verification with built-in UI (oval frame, progress ring, camera).

package/dist/index.js

@@ -1,5 +1,5 @@
 import { startLivenessWithUI } from "./ui";
-export { DEFAULT_MODEL_URL, DEFAULT_WASM_URL, LIVENESS_ERROR_CDN_NOT_AVAILABLE, LIVENESS_ERROR_OFFLINE, LIVENESS_STEP_COUNT, isCdnNotAvailableError, isOfflineError, LivenessError, } from "./engine";
+export { DEFAULT_MODEL_URL, DEFAULT_WASM_URL, LIVENESS_ERROR_CDN_NOT_AVAILABLE, LIVENESS_ERROR_OFFLINE, LIVENESS_STEP_COUNT, isCdnNotAvailableError, isOfflineError, resolveStepLabels, LivenessError, } from "./engine";
 let currentEngine = null;
 /**
  * Starts liveness verification with built-in UI (oval frame, progress ring, camera).

package/dist/ui.d.ts

@@ -1,4 +1,4 @@
-import { LivenessEngine, LivenessCallbacks, LivenessSoundOptions } from "./engine";
+import { LivenessEngine, LivenessCallbacks, LivenessSoundOptions, LivenessStepKey } from "./engine";
 export type LivenessTheme = {
     progressColor?: string;
     progressErrorColor?: string;
@@ -22,5 +22,9 @@ export type StartLivenessOptions = {
     wasmUrl?: string;
     callbacks: LivenessCallbacks;
     sounds?: LivenessSoundOptions;
+    /** Subset of challenges to run, e.g. `["nod", "blink", "mouth"]`. Default: all 5. */
+    steps?: LivenessStepKey[];
+    /** Shuffle the selected step order. Default true. */
+    shuffleSteps?: boolean;
 };
 export declare function startLivenessWithUI(options: StartLivenessOptions): LivenessEngine;

package/dist/ui.js

@@ -1,4 +1,4 @@
-import { LivenessEngine, LIVENESS_STEP_COUNT, LivenessError } from "./engine";
+import { LivenessEngine, LivenessError, resolveStepLabels } from "./engine";
 import { DEFAULT_SOUND_DATA_URLS } from "./default-sounds.generated";
 const DEFAULT_THEME = {
     progressColor: "#12c95c",
@@ -388,9 +388,11 @@ export function startLivenessWithUI(options) {
   `;
     root.appendChild(loading);
     // ── Step dots ──────────────────────────────────────────────────────────────
+    // Count derives from the active subset (`options.steps`), defaulting to all 5.
+    const sessionStepCount = resolveStepLabels(options.steps).length;
     const dotsEl = document.createElement("div");
     dotsEl.className = "lv-dots";
-    for (let i = 0; i < LIVENESS_STEP_COUNT; i++) {
+    for (let i = 0; i < sessionStepCount; i++) {
         const dot = document.createElement("div");
         dot.className = "lv-dot" + (i === 0 ? " active" : "");
         dotsEl.appendChild(dot);
@@ -420,7 +422,7 @@ export function startLivenessWithUI(options) {
     function setProgress(completedSteps) {
         if (!ringEl)
             return;
-        const filled = Math.min(completedSteps / LIVENESS_STEP_COUNT, 1);
+        const filled = Math.min(completedSteps / sessionStepCount, 1);
         const offset = P * (1 - filled);
         ringEl.setAttribute("stroke-dashoffset", offset.toFixed(1));
     }
@@ -450,10 +452,10 @@ export function startLivenessWithUI(options) {
     }
     function renderChallenge(stepIndex, stepLabel) {
         if (stepIndex === -1) {
-            setProgress(LIVENESS_STEP_COUNT);
+            setProgress(sessionStepCount);
             setCapturePulse();
             setHint(null);
-            setDots(LIVENESS_STEP_COUNT);
+            setDots(sessionStepCount);
             instruction.textContent = stepLabel;
             return;
         }
@@ -486,6 +488,8 @@ export function startLivenessWithUI(options) {
         modelUrl: options.modelUrl,
         wasmUrl: options.wasmUrl,
         sounds,
+        steps: options.steps,
+        shuffleSteps: options.shuffleSteps,
         callbacks: {
             onChallengeChanged: (stepIndex, stepLabel) => {
                 pendingChallenge = { stepIndex, stepLabel };
@@ -505,7 +509,7 @@ export function startLivenessWithUI(options) {
                 options.callbacks.onFailure?.(reason);
             },
             onSuccess: (imageBase64) => {
-                setProgress(LIVENESS_STEP_COUNT);
+                setProgress(sessionStepCount);
                 cleanup();
                 options.callbacks.onSuccess?.(imageBase64);
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daboss2003/liveness-web",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "Web liveness detection using MediaPipe Face Landmarker (CDN)",
   "keywords": [
     "liveness",

package/src/engine.ts

@@ -24,8 +24,15 @@ export type LivenessOptions = {
   wasmUrl?: string;
   callbacks?: LivenessCallbacks;
   sounds?: LivenessSoundOptions;
+  /** Subset of challenges to run. Default: all 5. Empty array, duplicates and unknown keys fall back to all 5. */
+  steps?: LivenessStepKey[];
+  /** Shuffle the selected step order. Default true. */
+  shuffleSteps?: boolean;
 };
 
+/** Identifier for a liveness challenge step. Lowercase, matches the sound-key form. */
+export type LivenessStepKey = "left" | "blink" | "right" | "nod" | "mouth";
+
 export const DEFAULT_MODEL_URL =
   "https://storage.googleapis.com/mediapipe-models/face_landmarker/face_landmarker/float16/1/face_landmarker.task";
 
@@ -132,22 +139,44 @@ export type Metrics = {
   faceSize:   number;
 };
 
-const STEP_LABELS = [
-  "Turn your head LEFT",
-  "Blink",
-  "Turn your head RIGHT",
-  "Nod your head",
-  "Open your mouth",
+/** Canonical step ordering. Each entry pairs the sound/identifier key with its display label. */
+const STEP_DEFS = [
+  { key: "left",  label: "Turn your head LEFT"  },
+  { key: "blink", label: "Blink"                },
+  { key: "right", label: "Turn your head RIGHT" },
+  { key: "nod",   label: "Nod your head"        },
+  { key: "mouth", label: "Open your mouth"      },
 ] as const;
 
+const STEP_LABELS: readonly string[] = STEP_DEFS.map(s => s.label);
+
+const STEP_KEY_TO_LABEL: Record<LivenessStepKey, string> = STEP_DEFS.reduce(
+  (acc, s) => { (acc as Record<string, string>)[s.key] = s.label; return acc; },
+  {} as Record<LivenessStepKey, string>,
+);
+
 /** Step label → sound key (filename without .mp3). Used so the correct sound plays regardless of randomized step order. */
-const STEP_LABEL_TO_SOUND: Record<string, string> = {
-  "Turn your head LEFT":  "left",
-  "Blink":                "blink",
-  "Turn your head RIGHT": "right",
-  "Nod your head":        "nod",
-  "Open your mouth":      "mouth",
-};
+const STEP_LABEL_TO_SOUND: Record<string, string> = STEP_DEFS.reduce(
+  (acc, s) => { acc[s.label] = s.key; return acc; },
+  {} as Record<string, string>,
+);
+
+/** Resolve a caller-supplied step-key array into the corresponding display labels.
+ *  Empty / undefined / all-invalid → default to all 5 steps. Duplicates are dropped. */
+export function resolveStepLabels(keys?: readonly LivenessStepKey[] | null): string[] {
+  if (!keys || keys.length === 0) return [...STEP_LABELS];
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const k of keys) {
+    const normalised = (typeof k === "string" ? k.toLowerCase() : "") as LivenessStepKey;
+    const label = STEP_KEY_TO_LABEL[normalised];
+    if (label && !seen.has(label)) {
+      seen.add(label);
+      out.push(label);
+    }
+  }
+  return out.length > 0 ? out : [...STEP_LABELS];
+}
 
 function shuffleArray<T>(array: readonly T[]): T[] {
   const out = [...array];
@@ -158,6 +187,7 @@ function shuffleArray<T>(array: readonly T[]): T[] {
   return out;
 }
 
+/** Default step count (5). The active session may have fewer if `options.steps` is set. */
 export const LIVENESS_STEP_COUNT = STEP_LABELS.length;
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -197,10 +227,13 @@ const config = {
   maxYawDuringNod:        40,
 
   // ── Blink ──────────────────────────────────────────────────────────────────
-  blinkClosedThreshold:  0.30,  // blendshape score = eyes closed
-  blinkOpenThreshold:    0.25,  // blendshape score = eyes open
+  // Real blinks easily hit 0.7+. Sustained squinting / glare / hooded eyelids hover at 0.25–0.40 —
+  // keep the "closed" threshold well above that band so passive eye states don't latch CLOSED.
+  blinkClosedThreshold:  0.50,
+  blinkOpenThreshold:    0.25,
   earClosedThreshold:    0.20,
   earOpenThreshold:      0.25,
+  blinkMinClosedMs:       60,   // eyes must be CLOSED for at least this long — filters out single-frame noise
   blinkMaxDurationMs:   4000,
   maxYawDuringBlink:     30,
   maxPitchDuringBlink:   30,
@@ -252,6 +285,7 @@ export class LivenessEngine {
   // ── Per-step sub-state ─────────────────────────────────────────────────────
   private blinkState:   "waitingClose" | "closed" = "waitingClose";
   private blinkCloseTs  = 0;
+  private blinkSeenOpen = false;  // gate: must observe at least one isEyeOpen frame before allowing a `closed` transition
   private nodState:     "neutral" | "down" = "neutral";
   private holdStart:    number | null = null;
 
@@ -342,10 +376,17 @@ export class LivenessEngine {
 
   // ── Public ─────────────────────────────────────────────────────────────────
 
+  /** Number of challenge steps in the active session (after applying `options.steps`). */
+  get stepCount(): number {
+    return this.steps.length > 0 ? this.steps.length : resolveStepLabels(this.opts.steps).length;
+  }
+
   async start(): Promise<void> {
     this.stopDetectionOnly();
     this.running      = true;
-    this.steps        = shuffleArray(STEP_LABELS).map((label, index) => ({ index, label }));
+    const selected    = resolveStepLabels(this.opts.steps);
+    const ordered     = this.opts.shuffleSteps === false ? selected : shuffleArray(selected);
+    this.steps        = ordered.map((label, index) => ({ index, label }));
     this.stepIndex    = 0;
     this.lastDetectTs = -1;
     this.lastOvalState = null;
@@ -511,6 +552,7 @@ export class LivenessEngine {
   private resetStepState(): void {
     this.blinkState      = "waitingClose";
     this.blinkCloseTs    = 0;
+    this.blinkSeenOpen   = false;
     this.nodState        = "neutral";
     this.holdStart       = null;
     this.baselineYaw     = null;
@@ -566,11 +608,18 @@ export class LivenessEngine {
           ? metrics.blinkScore < config.blinkOpenThreshold
           : metrics.ear > config.earOpenThreshold;
 
-        if (this.blinkState === "waitingClose" && isEyeClosed) {
+        // Confirm eyes were OPEN before we count any closed → open transition.
+        // Kills the "step starts mid-blink / mid-squint" false positive.
+        if (isEyeOpen) this.blinkSeenOpen = true;
+
+        if (this.blinkState === "waitingClose" && isEyeClosed && this.blinkSeenOpen) {
           this.blinkState   = "closed";
           this.blinkCloseTs = now;
         } else if (this.blinkState === "closed" && isEyeOpen) {
-          if (now - this.blinkCloseTs <= config.blinkMaxDurationMs) return this.advanceStep(now);
+          const dt = now - this.blinkCloseTs;
+          if (dt >= config.blinkMinClosedMs && dt <= config.blinkMaxDurationMs) return this.advanceStep(now);
+          // Closed phase too short (noise) or too long (eyes never reopened in time) — discard, wait for next attempt.
+          // blinkSeenOpen stays true — we've already confirmed the user can open their eyes.
           this.blinkState = "waitingClose";
         }
         break;

package/src/index.ts

@@ -10,9 +10,10 @@ export {
   LIVENESS_STEP_COUNT,
   isCdnNotAvailableError,
   isOfflineError,
+  resolveStepLabels,
   LivenessError,
 } from "./engine";
-export type { LivenessCallbacks, LivenessOptions, LivenessSoundOptions } from "./engine";
+export type { LivenessCallbacks, LivenessOptions, LivenessSoundOptions, LivenessStepKey } from "./engine";
 export type { LivenessEngine } from "./engine";
 
 let currentEngine: LivenessEngine | null = null;

package/src/ui.ts

@@ -1,4 +1,4 @@
-import { LivenessEngine, LIVENESS_STEP_COUNT, LivenessCallbacks, LivenessSoundOptions, LivenessError } from "./engine";
+import { LivenessEngine, LivenessCallbacks, LivenessSoundOptions, LivenessError, resolveStepLabels, LivenessStepKey } from "./engine";
 import { DEFAULT_SOUND_DATA_URLS } from "./default-sounds.generated";
 
 export type LivenessTheme = {
@@ -25,6 +25,10 @@ export type StartLivenessOptions = {
   wasmUrl?: string;
   callbacks: LivenessCallbacks;
   sounds?: LivenessSoundOptions;
+  /** Subset of challenges to run, e.g. `["nod", "blink", "mouth"]`. Default: all 5. */
+  steps?: LivenessStepKey[];
+  /** Shuffle the selected step order. Default true. */
+  shuffleSteps?: boolean;
 };
 
 const DEFAULT_THEME: Required<LivenessTheme> = {
@@ -445,9 +449,11 @@ export function startLivenessWithUI(options: StartLivenessOptions): LivenessEngi
   root.appendChild(loading);
 
   // ── Step dots ──────────────────────────────────────────────────────────────
+  // Count derives from the active subset (`options.steps`), defaulting to all 5.
+  const sessionStepCount = resolveStepLabels(options.steps).length;
   const dotsEl = document.createElement("div");
   dotsEl.className = "lv-dots";
-  for (let i = 0; i < LIVENESS_STEP_COUNT; i++) {
+  for (let i = 0; i < sessionStepCount; i++) {
     const dot = document.createElement("div");
     dot.className = "lv-dot" + (i === 0 ? " active" : "");
     dotsEl.appendChild(dot);
@@ -483,7 +489,7 @@ export function startLivenessWithUI(options: StartLivenessOptions): LivenessEngi
 
   function setProgress(completedSteps: number): void {
     if (!ringEl) return;
-    const filled = Math.min(completedSteps / LIVENESS_STEP_COUNT, 1);
+    const filled = Math.min(completedSteps / sessionStepCount, 1);
     const offset = P * (1 - filled);
     ringEl.setAttribute("stroke-dashoffset", offset.toFixed(1));
   }
@@ -515,10 +521,10 @@ export function startLivenessWithUI(options: StartLivenessOptions): LivenessEngi
 
   function renderChallenge(stepIndex: number, stepLabel: string): void {
     if (stepIndex === -1) {
-      setProgress(LIVENESS_STEP_COUNT);
+      setProgress(sessionStepCount);
       setCapturePulse();
       setHint(null);
-      setDots(LIVENESS_STEP_COUNT);
+      setDots(sessionStepCount);
       instruction.textContent = stepLabel;
       return;
     }
@@ -555,6 +561,8 @@ export function startLivenessWithUI(options: StartLivenessOptions): LivenessEngi
     modelUrl: options.modelUrl,
     wasmUrl: options.wasmUrl,
     sounds,
+    steps: options.steps,
+    shuffleSteps: options.shuffleSteps,
     callbacks: {
       onChallengeChanged: (stepIndex, stepLabel) => {
         pendingChallenge = { stepIndex, stepLabel };
@@ -574,7 +582,7 @@ export function startLivenessWithUI(options: StartLivenessOptions): LivenessEngi
         options.callbacks.onFailure?.(reason);
       },
       onSuccess: (imageBase64) => {
-        setProgress(LIVENESS_STEP_COUNT);
+        setProgress(sessionStepCount);
         cleanup();
         options.callbacks.onSuccess?.(imageBase64);
       },