@daboss2003/liveness-web 1.0.6 → 1.0.8

package/dist/ui.js

@@ -1,14 +1,17 @@
-import { LivenessEngine, LIVENESS_STEP_COUNT, LivenessError } from "./engine";
+import { LivenessEngine, LivenessError, resolveStepLabels } from "./engine";
 import { DEFAULT_SOUND_DATA_URLS } from "./default-sounds.generated";
-// ── Oval dimensions — keep in sync with engine.ts config.ovalCx/Cy/Rx/Ry ──
-const OVAL_W = 270;
-const OVAL_H = 360;
-const OVAL_TOP_PCT = 40;
-// Progress stroke sits on the main oval: ellipse inset by half stroke so outer edge aligns with cutout
-const STROKE_HALF = 1.75;
-const RX = OVAL_W / 2 - STROKE_HALF;
-const RY = OVAL_H / 2 - STROKE_HALF;
-const ELLIPSE_PERIMETER = Math.PI * (3 * (RX + RY) - Math.sqrt((3 * RX + RY) * (RX + 3 * RY)));
+const DEFAULT_THEME = {
+    progressColor: "#12c95c",
+    progressErrorColor: "#ff3b3b",
+    progressWidth: 3.5,
+    progressLineCap: "round",
+    overlayColor: "rgba(0,0,0,0.82)",
+    overlayErrorColor: "rgba(180,0,0,0.55)",
+};
+const DEFAULT_MIN_SIZE = 220;
+// Max radii (in CSS px) of the visible shape's cutout — see ─KEY DESIGN note below.
+const OVAL_BASE = { w: 270, h: 360 };
+const CIRCLE_BASE = 270;
 /** Step label (from engine) → hint icon kind. Use this so the correct icon shows when steps are randomized. */
 const STEP_LABEL_TO_HINT = {
     "Turn your head LEFT": "left",
@@ -19,32 +22,44 @@ const STEP_LABEL_TO_HINT = {
 };
 // ─────────────────────────────────────────────────────────────────────────────
 // Styles
+//
+// KEY DESIGN: `--oval-w` and `--oval-h` are RADII (not full dimensions) of the
+// visible cutout, because the CSS radial-gradient mask consumes them as
+// `ellipse <hRadius> <vRadius>`. The SVG ring wrapper is therefore sized to
+// `2 * var(--oval-w)` × `2 * var(--oval-h)` so it aligns to the cutout edge.
 // ─────────────────────────────────────────────────────────────────────────────
-function createStyles() {
+function createStyles(cfg) {
+    const { embed, theme, minRadius, dims, ovalTopPct } = cfg;
+    const sizeUnit = embed ? "cqmin" : "vmin";
+    const pulseHi = (theme.progressWidth * 10 / 7).toFixed(2); // ~1.43× — preserves 3.5→5 ratio of the original
     const s = document.createElement("style");
     s.textContent = `
-    :root {
-      --lv-green: #12c95c;
-      --lv-red:   #ff3b3b;
-      --lv-white: #ffffff;
-      --lv-dark:  rgba(0,0,0,0.82);
+    .lv-outer {
+      position: absolute;
+      inset: 0;
+      container-type: size;
+      overflow: hidden;
     }
 
     .lv-root {
-      position: fixed;
+      position: ${embed ? "absolute" : "fixed"};
       inset: 0;
-      z-index: 999999;
-      background: #000;
+      z-index: ${embed ? "1" : "999999"};
+      background: ${embed ? "transparent" : "#000"};
       font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "Segoe UI", sans-serif;
-      color: var(--lv-white);
+      color: #ffffff;
       overflow: hidden;
       display: flex;
       flex-direction: column;
       align-items: center;
-      /* Radii: keep oval inside viewport on mobile (diameter = 2× this), cap at desktop */
-      --oval-w: min(45vmin, ${OVAL_W}px);
-      --oval-h: min(60vmin, ${OVAL_H}px);
-      /* Half-height of the visible oval for positioning (oval uses full w/h as radii) */
+
+      --lv-progress:       ${theme.progressColor};
+      --lv-progress-error: ${theme.progressErrorColor};
+      --lv-overlay:        ${theme.overlayColor};
+      --lv-overlay-error:  ${theme.overlayErrorColor};
+
+      --oval-w: clamp(${minRadius}px, 45${sizeUnit}, ${dims.wMax}px);
+      --oval-h: calc(var(--oval-w) * ${dims.aspectH});
       --oval-half-h: var(--oval-h);
     }
 
@@ -58,15 +73,12 @@ function createStyles() {
       overflow: hidden;
     }
     .lv-video {
-      /* Fill the container while keeping aspect ratio */
       width: 100%;
       height: 100%;
       object-fit: cover;
-      /* Mirror so it feels like a selfie camera */
       transform: scaleX(-1);
       opacity: 0;
       transition: opacity 0.2s ease;
-      /* Clip the video to the oval using clip-path on the parent */
     }
     .lv-video.is-playing { opacity: 1; }
     .lv-video::-webkit-media-controls,
@@ -88,25 +100,35 @@ function createStyles() {
       pointer-events: none;
     }
     .lv-root:not(.lv-is-loading) .lv-loading { display: none; }
+
+    /* When the host owns instructions, hide every SDK label/animation. Sounds + ring stay. */
+    .lv-root.lv-no-instructions .lv-loading,
+    .lv-root.lv-no-instructions .lv-dots,
+    .lv-root.lv-no-instructions .lv-instruction,
+    .lv-root.lv-no-instructions .lv-pos-hint,
+    .lv-root.lv-no-instructions .lv-hint-icon {
+      display: none !important;
+    }
+
     .lv-loading {
       position: absolute;
       z-index: 2;
       left: 50%;
-      top: ${OVAL_TOP_PCT}%;
+      top: ${ovalTopPct}%;
       transform: translate(-50%, -50%);
       display: flex;
       flex-direction: column;
       align-items: center;
       gap: 8px;
       text-align: center;
-      color: var(--lv-white);
+      color: #ffffff;
       text-shadow: 0 1px 6px rgba(0,0,0,0.5);
     }
     .lv-spinner {
       width: 32px;
       height: 32px;
       border: 3px solid rgba(255,255,255,0.25);
-      border-top-color: var(--lv-white);
+      border-top-color: #ffffff;
       border-radius: 50%;
       animation: lv-spin 0.9s linear infinite;
     }
@@ -117,35 +139,31 @@ function createStyles() {
     }
     @keyframes lv-spin { to { transform: rotate(360deg); } }
 
-    /* ── Dark overlay with oval cutout ──────────────────────────────────── */
+    /* ── Dark overlay with shape cutout ────────────────────────────────── */
     .lv-overlay {
       position: absolute;
       inset: 0;
-      /* Ellipse size (radii): full oval w/h so cutout is large; ring is scaled to match */
       --ow: var(--oval-w);
       --oh: var(--oval-h);
-      background: var(--lv-dark);
+      background: var(--lv-overlay);
       -webkit-mask-image: radial-gradient(
-        ellipse var(--ow) var(--oh) at 50% ${OVAL_TOP_PCT}%,
+        ellipse var(--ow) var(--oh) at 50% ${ovalTopPct}%,
         transparent 99%, black 100%
       );
       mask-image: radial-gradient(
-        ellipse var(--ow) var(--oh) at 50% ${OVAL_TOP_PCT}%,
+        ellipse var(--ow) var(--oh) at 50% ${ovalTopPct}%,
         transparent 99%, black 100%
       );
       pointer-events: none;
       transition: background 0.25s;
     }
-    .lv-overlay.out-of-oval {
-      /* Tint red when face isn't in position */
-      background: rgba(180,0,0,0.55);
-    }
+    .lv-overlay.out-of-oval { background: var(--lv-overlay-error); }
 
-    /* ── Oval SVG ring (2× so progress sits on the main oval boundary) ───── */
+    /* ── Progress ring (2× so its stroke sits on the cutout edge) ──────── */
     .lv-ring-wrap {
       position: absolute;
       left: 50%;
-      top: ${OVAL_TOP_PCT}%;
+      top: ${ovalTopPct}%;
       transform: translate(-50%, -50%);
       width: calc(2 * var(--oval-w));
       height: calc(2 * var(--oval-h));
@@ -154,38 +172,20 @@ function createStyles() {
     .lv-ring-wrap svg { width: 100%; height: 100%; overflow: visible; }
     .lv-ring-progress {
       fill: none;
-      stroke: var(--lv-green);
-      stroke-width: 3.5;
-      stroke-linecap: round;
+      stroke: var(--lv-progress);
+      stroke-width: ${theme.progressWidth};
+      stroke-linecap: ${theme.progressLineCap};
       transition: stroke-dashoffset 0.45s cubic-bezier(.4,0,.2,1), stroke 0.25s;
       transform: rotate(0deg);
       transform-origin: center;
     }
-    .lv-ring-progress.out-of-oval { stroke: var(--lv-red); }
-
-    /* ── Top header bar ──────────────────────────────────────────────────── */
-    .lv-header {
-      position: relative;
-      z-index: 2;
-      width: 100%;
-      display: flex;
-      align-items: center;
-      justify-content: center;
-      padding: 18px 20px 0;
-      gap: 10px;
-    }
-    .lv-header-title {
-      font-size: 15px;
-      font-weight: 600;
-      letter-spacing: 0.02em;
-      opacity: 0.9;
-    }
+    .lv-ring-progress.out-of-oval { stroke: var(--lv-progress-error); }
 
-    /* ── Step dots ───────────────────────────────────────────────────────── */
+    /* ── Step dots ─────────────────────────────────────────────────────── */
     .lv-dots {
       position: absolute;
       z-index: 2;
-      top: calc(${OVAL_TOP_PCT}% + var(--oval-half-h) + 20px);
+      top: calc(${ovalTopPct}% + var(--oval-half-h) + 20px);
       left: 50%;
       transform: translateX(-50%);
       display: flex;
@@ -196,14 +196,14 @@ function createStyles() {
       background: rgba(255,255,255,0.2);
       transition: background 0.3s, transform 0.3s;
     }
-    .lv-dot.active { background: var(--lv-green); transform: scale(1.3); }
-    .lv-dot.done  { background: var(--lv-green); opacity: .5; transform: scale(1); }
+    .lv-dot.active { background: var(--lv-progress); transform: scale(1.3); }
+    .lv-dot.done  { background: var(--lv-progress); opacity: .5; transform: scale(1); }
 
-    /* ── Instruction text ────────────────────────────────────────────────── */
+    /* ── Instruction text ──────────────────────────────────────────────── */
     .lv-instruction {
       position: absolute;
       z-index: 2;
-      top: calc(${OVAL_TOP_PCT}% + var(--oval-half-h) + 52px);
+      top: calc(${ovalTopPct}% + var(--oval-half-h) + 52px);
       left: 50%;
       transform: translateX(-50%);
       white-space: nowrap;
@@ -215,16 +215,16 @@ function createStyles() {
       transition: opacity 0.2s;
     }
 
-    /* ── "Move closer / centre your face" hint ───────────────────────────── */
+    /* ── "Move closer / centre your face" hint ─────────────────────────── */
     .lv-pos-hint {
       position: absolute;
       z-index: 2;
-      top: calc(${OVAL_TOP_PCT}% + var(--oval-half-h) + 84px);
+      top: calc(${ovalTopPct}% + var(--oval-half-h) + 84px);
       left: 50%;
       transform: translateX(-50%);
       font-size: 13px;
       font-weight: 500;
-      color: var(--lv-red);
+      color: var(--lv-progress-error);
       opacity: 0;
       white-space: nowrap;
       text-shadow: 0 1px 6px rgba(0,0,0,0.5);
@@ -233,12 +233,12 @@ function createStyles() {
     }
     .lv-pos-hint.visible { opacity: 1; }
 
-    /* ── Animated gesture icon ───────────────────────────────────────────── */
+    /* ── Animated gesture icon ─────────────────────────────────────────── */
     .lv-hint-icon {
       position: absolute;
       z-index: 2;
       left: 50%;
-      top: ${OVAL_TOP_PCT}%;
+      top: ${ovalTopPct}%;
       transform: translate(-50%, -50%);
       width: 52px;
       height: 52px;
@@ -250,7 +250,6 @@ function createStyles() {
     }
     .lv-hint-icon svg { width: 40px; height: 40px; }
 
-    /* Arrow bounce animations */
     @keyframes lv-left  { 0%,100%{transform:translateX(0)}  50%{transform:translateX(-9px)} }
     @keyframes lv-right { 0%,100%{transform:translateX(0)}  50%{transform:translateX(9px)}  }
     @keyframes lv-down  { 0%,100%{transform:translateY(0)}  50%{transform:translateY(8px)}  }
@@ -260,7 +259,7 @@ function createStyles() {
     }
     @keyframes lv-mouth {
       0%,60%,100% { transform: scaleY(0.35); }
-      30%          { transform: scaleY(1); }
+      30%         { transform: scaleY(1); }
     }
 
     .lv-anim-left  { animation: lv-left  1s ease-in-out infinite; }
@@ -269,14 +268,13 @@ function createStyles() {
     .lv-eye        { animation: lv-blink 2s ease-in-out infinite; transform-origin: center; }
     .lv-jaw        { animation: lv-mouth 1.5s ease-in-out infinite; transform-origin: top center; }
 
-    /* ── Capture pulse ──────────────────────────────────────────────────── */
+    /* ── Capture pulse ────────────────────────────────────────────────── */
     @keyframes lv-pulse {
-      0%,100% { stroke-width: 3.5; opacity: 1; }
-      50%     { stroke-width: 5;   opacity: 0.55; }
+      0%,100% { stroke-width: ${theme.progressWidth}; opacity: 1; }
+      50%     { stroke-width: ${pulseHi};             opacity: 0.55; }
     }
-    .lv-ring-pulse { animation: lv-pulse 1s ease-in-out infinite; stroke: var(--lv-green) !important; }
+    .lv-ring-pulse { animation: lv-pulse 1s ease-in-out infinite; stroke: var(--lv-progress) !important; }
 
-    /* ── Hidden canvas for capture ───────────────────────────────────────── */
     .lv-canvas {
       position: absolute;
       width: 0; height: 0;
@@ -304,11 +302,49 @@ function hintSvg(kind) {
 // Main factory
 // ─────────────────────────────────────────────────────────────────────────────
 export function startLivenessWithUI(options) {
+    const embed = !!options.embed;
+    const shape = options.shape ?? "oval";
+    const showInstructions = options.showInstructions ?? true;
+    const theme = { ...DEFAULT_THEME, ...(options.theme ?? {}) };
+    const minSize = options.minSize ?? DEFAULT_MIN_SIZE;
+    const minRadius = Math.max(20, Math.floor(minSize / 2));
+    const dims = shape === "circle"
+        ? { wMax: CIRCLE_BASE, hMax: CIRCLE_BASE, aspectH: 1 }
+        : { wMax: OVAL_BASE.w, hMax: OVAL_BASE.h, aspectH: OVAL_BASE.h / OVAL_BASE.w };
+    // When the host owns instructions, the area below the cutout isn't needed,
+    // so we centre the shape vertically. Otherwise keep the original 40% slot.
+    const ovalTopPct = showInstructions ? 40 : 50;
+    // Ring geometry derives from dims + stroke width
+    const SVG_W = dims.wMax;
+    const SVG_H = dims.hMax;
+    const STROKE_HALF = theme.progressWidth / 2;
+    const RX = SVG_W / 2 - STROKE_HALF;
+    const RY = SVG_H / 2 - STROKE_HALF;
+    const ELLIPSE_PERIMETER = Math.PI * (3 * (RX + RY) - Math.sqrt((3 * RX + RY) * (RX + 3 * RY)));
     const container = options.container ?? document.body;
+    // ── Mount layer (wrapper only needed for embed so cqmin has a sized container) ──
+    let outerEl = null;
+    let mountPoint;
+    if (embed) {
+        const computed = getComputedStyle(container);
+        if (computed.position === "static" && container !== document.body) {
+            container.style.position = "relative";
+        }
+        const wrapper = document.createElement("div");
+        wrapper.className = "lv-outer";
+        container.appendChild(wrapper);
+        outerEl = wrapper;
+        mountPoint = wrapper;
+    }
+    else {
+        mountPoint = container;
+    }
     // ── Root shell ─────────────────────────────────────────────────────────────
     const root = document.createElement("div");
-    root.className = "lv-root lv-is-loading";
-    root.appendChild(createStyles());
+    root.className = "lv-root lv-is-loading"
+        + (embed ? " lv-embed" : "")
+        + (!showInstructions ? " lv-no-instructions" : "");
+    root.appendChild(createStyles({ embed, showInstructions, theme, minRadius, dims, ovalTopPct }));
     // ── Video background ───────────────────────────────────────────────────────
     const videoBg = document.createElement("div");
     videoBg.className = "lv-video-bg";
@@ -320,16 +356,16 @@ export function startLivenessWithUI(options) {
     video.setAttribute("muted", "");
     videoBg.appendChild(video);
     root.appendChild(videoBg);
-    // ── Dark overlay with oval cutout ──────────────────────────────────────────
+    // ── Dark overlay with shape cutout ─────────────────────────────────────────
     const overlay = document.createElement("div");
     overlay.className = "lv-overlay";
     root.appendChild(overlay);
-    // ── Progress ring (ellipse pathLength = perimeter so dash offset matches) ───
-    const rx = OVAL_W / 2, ry = OVAL_H / 2;
+    // ── Progress ring ──────────────────────────────────────────────────────────
+    const rx = SVG_W / 2, ry = SVG_H / 2;
     const ringWrap = document.createElement("div");
     ringWrap.className = "lv-ring-wrap";
     ringWrap.innerHTML = `
-    <svg viewBox="0 0 ${OVAL_W} ${OVAL_H}">
+    <svg viewBox="0 0 ${SVG_W} ${SVG_H}">
       <ellipse class="lv-ring-progress"
         cx="${rx}" cy="${ry}" rx="${RX}" ry="${RY}"
         pathLength="${ELLIPSE_PERIMETER.toFixed(1)}"
@@ -338,12 +374,12 @@ export function startLivenessWithUI(options) {
         transform="rotate(-90 ${rx} ${ry})"/>
     </svg>`;
     root.appendChild(ringWrap);
-    // ── Gesture hint icon (inside the oval) ────────────────────────────────────
+    // ── Gesture hint icon ──────────────────────────────────────────────────────
     const hintIcon = document.createElement("div");
     hintIcon.className = "lv-hint-icon";
     hintIcon.setAttribute("aria-hidden", "true");
     root.appendChild(hintIcon);
-    // ── Loading spinner (shown until model is ready) ───────────────────────────
+    // ── Loading spinner ────────────────────────────────────────────────────────
     const loading = document.createElement("div");
     loading.className = "lv-loading";
     loading.innerHTML = `
@@ -351,15 +387,12 @@ export function startLivenessWithUI(options) {
     <div class="lv-loading-text">Preparing camera...</div>
   `;
     root.appendChild(loading);
-    // ── Header ─────────────────────────────────────────────────────────────────
-    // const header = document.createElement("div");
-    // header.className = "lv-header";
-    // header.innerHTML = `<span class="lv-header-title">Face Verification</span>`;
-    // root.appendChild(header);
     // ── 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);
@@ -370,7 +403,7 @@ export function startLivenessWithUI(options) {
     instruction.className = "lv-instruction";
     instruction.textContent = "Position your face in the oval";
     root.appendChild(instruction);
-    // ── Position hint (shows when face is out of oval) ─────────────────────────
+    // ── Position hint ──────────────────────────────────────────────────────────
     const posHint = document.createElement("div");
     posHint.className = "lv-pos-hint";
     root.appendChild(posHint);
@@ -378,7 +411,8 @@ export function startLivenessWithUI(options) {
     const canvas = document.createElement("canvas");
     canvas.className = "lv-canvas";
     root.appendChild(canvas);
-    container.appendChild(root);
+    mountPoint.appendChild(root);
+    const topEl = outerEl ?? root;
     const ringEl = ringWrap.querySelector(".lv-ring-progress");
     const dots = Array.from(dotsEl.querySelectorAll(".lv-dot"));
     const P = ELLIPSE_PERIMETER;
@@ -388,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));
     }
@@ -418,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;
         }
@@ -436,7 +470,7 @@ export function startLivenessWithUI(options) {
         video.removeEventListener("playing", onVideoPlaying);
         video.removeEventListener("pause", onVideoPause);
         video.removeEventListener("waiting", onVideoPause);
-        root.remove();
+        topEl.remove();
     }
     // ── Engine ─────────────────────────────────────────────────────────────────
     // Use options.sounds if provided; otherwise use embedded default sounds (works in any host)
@@ -454,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 };
@@ -473,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.6",
+  "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;