@smileid/usesmileid 12.0.0-beta01

package/src/presentation/screen/__tests__/feedback_debouncer.test.ts

@@ -0,0 +1,111 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { UseSmileIDFeedbackDebouncer } from "../helpers/feedback_debouncer";
+
+const DELAY = 300;
+
+describe("UseSmileIDFeedbackDebouncer", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  function makeDebouncer(options?: {
+    isImmediate?: (value: string) => boolean;
+    initialValue?: string;
+  }) {
+    const emitted: string[] = [];
+    const debouncer = new UseSmileIDFeedbackDebouncer<string>({
+      emit: (value) => emitted.push(value),
+      delayMs: DELAY,
+      ...(options?.isImmediate ? { isImmediate: options.isImmediate } : {}),
+      ...(options?.initialValue !== undefined
+        ? { initialValue: options.initialValue }
+        : {}),
+    });
+    return { debouncer, emitted };
+  }
+
+  it("fires exactly once for a steady stream of the same value", () => {
+    // Frames republish every 100 ms — faster than the 300 ms window; a
+    // naive trailing debounce would never fire.
+    const { debouncer, emitted } = makeDebouncer();
+    for (let i = 0; i < 10; i++) {
+      debouncer.publish("si_capture_smile");
+      vi.advanceTimersByTime(100);
+    }
+    expect(emitted).toEqual(["si_capture_smile"]);
+    vi.advanceTimersByTime(1000);
+    expect(emitted).toEqual(["si_capture_smile"]);
+  });
+
+  it("settles a changing stream to the latest value", () => {
+    const { debouncer, emitted } = makeDebouncer();
+    debouncer.publish("si_capture_too_close");
+    vi.advanceTimersByTime(100);
+    debouncer.publish("si_capture_too_far");
+    vi.advanceTimersByTime(100);
+    debouncer.publish("si_capture_center_face");
+    expect(emitted).toEqual([]);
+    vi.advanceTimersByTime(DELAY);
+    expect(emitted).toEqual(["si_capture_center_face"]);
+  });
+
+  it("re-publishing the settled value is a no-op", () => {
+    const { debouncer, emitted } = makeDebouncer();
+    debouncer.publish("si_capture_smile");
+    vi.advanceTimersByTime(DELAY);
+    debouncer.publish("si_capture_smile");
+    vi.advanceTimersByTime(DELAY);
+    expect(emitted).toEqual(["si_capture_smile"]);
+  });
+
+  it("treats the initial value as already settled", () => {
+    const { debouncer, emitted } = makeDebouncer({
+      initialValue: "si_capture_initial_instruction",
+    });
+    debouncer.publish("si_capture_initial_instruction");
+    vi.advanceTimersByTime(DELAY);
+    expect(emitted).toEqual([]);
+  });
+
+  it("emits immediate values synchronously, bypassing the window", () => {
+    const { debouncer, emitted } = makeDebouncer({
+      isImmediate: (value) => value === "si_selfie_capture_complete",
+    });
+    debouncer.publish("si_capturing");
+    vi.advanceTimersByTime(100);
+    debouncer.publish("si_selfie_capture_complete");
+    expect(emitted).toEqual(["si_selfie_capture_complete"]);
+    vi.advanceTimersByTime(1000);
+    expect(emitted).toEqual(["si_selfie_capture_complete"]);
+  });
+
+  it("re-emits even a repeated value after reset", () => {
+    const { debouncer, emitted } = makeDebouncer();
+    debouncer.publish("si_capture_smile");
+    vi.advanceTimersByTime(DELAY);
+    debouncer.reset();
+    debouncer.publish("si_capture_smile");
+    vi.advanceTimersByTime(DELAY);
+    expect(emitted).toEqual(["si_capture_smile", "si_capture_smile"]);
+  });
+
+  it("seed emits synchronously and counts as settled", () => {
+    const { debouncer, emitted } = makeDebouncer();
+    debouncer.seed("si_ess_capture_initial_instruction");
+    expect(emitted).toEqual(["si_ess_capture_initial_instruction"]);
+    debouncer.publish("si_ess_capture_initial_instruction");
+    vi.advanceTimersByTime(DELAY);
+    expect(emitted).toEqual(["si_ess_capture_initial_instruction"]);
+  });
+
+  it("dispose cancels the in-flight window without emitting", () => {
+    const { debouncer, emitted } = makeDebouncer();
+    debouncer.publish("si_capture_smile");
+    debouncer.dispose();
+    vi.advanceTimersByTime(1000);
+    expect(emitted).toEqual([]);
+  });
+});

package/src/presentation/screen/__tests__/instructions_screen_helpers.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it } from "vitest";
+import { UseSmileIDLocalizations } from "../../../l10n/use_smile_id_localizations";
+import {
+  resolveInstructionsConfig,
+  resolvedHeroAnimation,
+} from "../helpers/instructions_screen_helpers";
+import {
+  DOCUMENT_GREEN_BOOK_HERO_ANIMATION,
+  DOCUMENT_GUIDELINES,
+  DOCUMENT_HERO_ANIMATION,
+  ESS_HERO_ANIMATION,
+  SELFIE_GUIDELINES,
+  SELFIE_HERO_ANIMATION,
+} from "../../flow/model/instructions_defaults";
+import type { InstructionGuideline } from "../../flow/model/instruction_guideline";
+import { DocumentType } from "../../../core/models/document_type";
+
+const loc = new UseSmileIDLocalizations({});
+// A partner-supplied hero can be a string asset path (a valid HeroAnimationSource).
+const CUSTOM_HERO = "partner-hero.json";
+
+describe("resolveInstructionsConfig", () => {
+  it("falls back to localized defaults and the shared guidelines when unset", () => {
+    const resolved = resolveInstructionsConfig(
+      {},
+      { enhancedLivenessEnabled: false },
+      loc,
+    );
+    expect(resolved.titlePrefix).toBe(loc.siInstructionsTitlePrefix);
+    expect(resolved.titleEmphasis).toBe(loc.siInstructionsEmphasisSelfie);
+    expect(resolved.guidelinesSectionTitle).toBe(
+      loc.siInstructionsCaptureGuidelines,
+    );
+    // Empty guidelines resolve to the shared frozen default (same reference).
+    expect(resolved.guidelines).toBe(SELFIE_GUIDELINES);
+    expect(resolved.heroSource).toBe(SELFIE_HERO_ANIMATION);
+    expect(resolved.showAttribution).toBe(true);
+    expect(resolved.showHeroOval).toBe(true);
+    expect(resolved.showHeroOvalProgress).toBe(true);
+  });
+
+  it("honors explicit overrides verbatim", () => {
+    const guidelines: InstructionGuideline[] = [SELFIE_GUIDELINES[0]!];
+    const resolved = resolveInstructionsConfig(
+      {
+        titlePrefix: "Ready for your",
+        titleEmphasis: "scan",
+        guidelinesSectionTitle: "Tips",
+        guidelines,
+        showAttribution: false,
+        showHeroOval: false,
+      },
+      { enhancedLivenessEnabled: false },
+      loc,
+    );
+    expect(resolved.titlePrefix).toBe("Ready for your");
+    expect(resolved.titleEmphasis).toBe("scan");
+    expect(resolved.guidelinesSectionTitle).toBe("Tips");
+    expect(resolved.guidelines).toBe(guidelines);
+    expect(resolved.showAttribution).toBe(false);
+    expect(resolved.showHeroOval).toBe(false);
+  });
+
+  it("suppresses the rising oval progress fill under Enhanced Smart Selfie", () => {
+    // ESS capture has no single rising-progress ring to preview.
+    expect(
+      resolveInstructionsConfig({}, { enhancedLivenessEnabled: true }, loc)
+        .showHeroOvalProgress,
+    ).toBe(false);
+    expect(
+      resolveInstructionsConfig({}, { enhancedLivenessEnabled: false }, loc)
+        .showHeroOvalProgress,
+    ).toBe(true);
+  });
+});
+
+describe("resolveInstructionsConfig — document variant", () => {
+  it("uses the document displayName, document guidelines, per-type hero, and no oval", () => {
+    const resolved = resolveInstructionsConfig(
+      {},
+      {
+        enhancedLivenessEnabled: false,
+        documentType: DocumentType.SouthAfricaGreenBook,
+      },
+      loc,
+    );
+    expect(resolved.titleEmphasis).toBe("Green Book");
+    expect(resolved.guidelines).toBe(DOCUMENT_GUIDELINES);
+    expect(resolved.heroSource).toBe(DOCUMENT_GREEN_BOOK_HERO_ANIMATION);
+    expect(resolved.showHeroOval).toBe(false);
+    expect(resolved.showHeroOvalProgress).toBe(false);
+    // The prefix still comes from the shared localized default.
+    expect(resolved.titlePrefix).toBe(loc.siInstructionsTitlePrefix);
+  });
+
+  it("falls back to the generic document hero for GenericDocument", () => {
+    const resolved = resolveInstructionsConfig(
+      {},
+      {
+        enhancedLivenessEnabled: false,
+        documentType: DocumentType.GenericDocument(),
+      },
+      loc,
+    );
+    expect(resolved.heroSource).toBe(DOCUMENT_HERO_ANIMATION);
+    expect(resolved.titleEmphasis).toBe("Document");
+  });
+
+  it("respects partner title/guideline overrides but always hides the oval for documents", () => {
+    const customGuidelines: InstructionGuideline[] = [SELFIE_GUIDELINES[0]!];
+    const resolved = resolveInstructionsConfig(
+      {
+        titleEmphasis: "My ID",
+        guidelines: customGuidelines,
+        showHeroOval: true,
+      },
+      { enhancedLivenessEnabled: false, documentType: DocumentType.Passport },
+      loc,
+    );
+    // Title + guidelines respect the partner override…
+    expect(resolved.titleEmphasis).toBe("My ID");
+    expect(resolved.guidelines).toBe(customGuidelines);
+    // …but a document flow never shows the face oval, even when asked.
+    expect(resolved.showHeroOval).toBe(false);
+  });
+});
+
+describe("resolvedHeroAnimation", () => {
+  it("uses the bundled selfie hero by default", () => {
+    expect(resolvedHeroAnimation(undefined, false)).toBe(SELFIE_HERO_ANIMATION);
+  });
+
+  it("swaps the default hero for the ESS hero when enhanced liveness is on", () => {
+    expect(resolvedHeroAnimation(undefined, true)).toBe(ESS_HERO_ANIMATION);
+  });
+
+  it("respects a partner-supplied hero even under enhanced liveness", () => {
+    // Concrete scenario: a partner set their own hero; ESS must not clobber it.
+    expect(resolvedHeroAnimation(CUSTOM_HERO, true)).toBe(CUSTOM_HERO);
+    expect(resolvedHeroAnimation(CUSTOM_HERO, false)).toBe(CUSTOM_HERO);
+  });
+});

package/src/presentation/screen/__tests__/preview_screen_helpers.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { resolvePreviewState } from "../helpers/preview_screen_helpers";
+
+describe("resolvePreviewState", () => {
+  it("reports no image when capturedSelfiePath is omitted", () => {
+    // Concrete scenario: the user lands on the preview screen
+    // without a successful capture (e.g. orchestrator routed here
+    // by mistake). Both Accept and Retake should be disabled —
+    // there's nothing to act on.
+    const state = resolvePreviewState({});
+    expect(state.hasImage).toBe(false);
+    expect(state.canAccept).toBe(false);
+    expect(state.canRetake).toBe(false);
+  });
+
+  it("treats an empty-string path the same as no image", () => {
+    // Concrete scenario: a future bug sets `capturedSelfiePath = ''`
+    // instead of leaving it undefined. The image card would render
+    // a broken `file:///` source. Pin the empty-string fallback so
+    // the screen stays in the "no image" branch.
+    const state = resolvePreviewState({ capturedSelfiePath: "" });
+    expect(state.hasImage).toBe(false);
+    expect(state.canAccept).toBe(false);
+  });
+
+  it("enables Accept and Retake when a path is present and retake is allowed", () => {
+    const state = resolvePreviewState({
+      capturedSelfiePath: "file:///selfie.jpg",
+    });
+    expect(state.hasImage).toBe(true);
+    expect(state.canAccept).toBe(true);
+    expect(state.canRetake).toBe(true);
+  });
+
+  it("disables Retake when partner forces allowRetake=false but keeps Accept enabled", () => {
+    // Concrete scenario: partner with a strict capture policy
+    // commits the user to the first capture. Accept must still
+    // work; Reject must hide.
+    const state = resolvePreviewState({
+      capturedSelfiePath: "file:///selfie.jpg",
+      allowRetake: false,
+    });
+    expect(state.canAccept).toBe(true);
+    expect(state.canRetake).toBe(false);
+  });
+
+  it("defaults allowRetake to true when omitted", () => {
+    const state = resolvePreviewState({
+      capturedSelfiePath: "file:///selfie.jpg",
+    });
+    expect(state.canRetake).toBe(true);
+  });
+});

package/src/presentation/screen/__tests__/processing_screen_helpers.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { resolveOverlayStateForProcessing } from "../helpers/processing_screen_helpers";
+import { UseSmileIDOverlayState } from "../../state/use_smile_id_overlay_state";
+
+describe("resolveOverlayStateForProcessing", () => {
+  it("maps loading → PROCESSING (capture-progress border)", () => {
+    // Concrete scenario: while submitting, the oval should pulse
+    // with the capture-progress colour to telegraph "active work".
+    expect(resolveOverlayStateForProcessing("loading")).toBe(
+      UseSmileIDOverlayState.PROCESSING,
+    );
+  });
+
+  it("maps success → READY (green border)", () => {
+    // Concrete scenario: server confirmed the job. Oval flips to
+    // the green ovalActive colour so the user gets an immediate
+    // affirmative cue under the bottom-card success content.
+    expect(resolveOverlayStateForProcessing("success")).toBe(
+      UseSmileIDOverlayState.READY,
+    );
+  });
+
+  it("maps failed → IDLE (neutral border, not warning)", () => {
+    // Concrete scenario: server rejected. The bottom-card already
+    // surfaces the failure (warning indicator + Retry/Exit). The
+    // oval drops to neutral so the failure messaging isn't
+    // visually duplicated by an angry red border.
+    expect(resolveOverlayStateForProcessing("failed")).toBe(
+      UseSmileIDOverlayState.IDLE,
+    );
+  });
+
+  it("is exhaustive over the three processing kinds", () => {
+    const kinds = ["loading", "success", "failed"] as const;
+    for (const k of kinds) {
+      expect(resolveOverlayStateForProcessing(k)).toBeTruthy();
+    }
+  });
+});

package/src/presentation/screen/__tests__/scan_state_to_overlay_state.test.ts

@@ -0,0 +1,203 @@
+import { describe, expect, it } from "vitest";
+import { ScanStateType } from "@smileid/usesmileid_bridge";
+import type { ScanState } from "@smileid/usesmileid_bridge";
+import { mapScanStateToOverlayState } from "../helpers/scan_state_to_overlay_state";
+import { UseSmileIDOverlayState } from "../../state/use_smile_id_overlay_state";
+import { CaptureType } from "../../../core/models/ml_config";
+
+/**
+ * Pure-logic tests for the helper that translates the analyzer's
+ * `ScanState` machine into the SDK's visual overlay enum. These cover
+ * what the legacy screen tests pinned via the now-removed
+ * `overlayState=` prop — the screen now derives overlay state from
+ * `scanState` per frame, so testing the mapping in isolation gives the
+ * same coverage without standing up a real analyzer + frame stream.
+ */
+describe("mapScanStateToOverlayState", () => {
+  it("maps the initial state to INSTRUCTION for selfie", () => {
+    const state: ScanState = { type: ScanStateType.Initial };
+    expect(mapScanStateToOverlayState(state, CaptureType.selfie)).toBe(
+      UseSmileIDOverlayState.INSTRUCTION,
+    );
+  });
+
+  it("maps the initial state to INSTRUCTION for document", () => {
+    const state: ScanState = { type: ScanStateType.Initial };
+    expect(mapScanStateToOverlayState(state, CaptureType.document)).toBe(
+      UseSmileIDOverlayState.INSTRUCTION,
+    );
+  });
+
+  it("maps a satisfied selfie state to READY", () => {
+    // READY drives the bottom-to-top fill animation on the face oval —
+    // the analyzer signalling "satisfied" means the pipeline is about
+    // to emit captured frames.
+    const state: ScanState = { type: ScanStateType.Satisfied };
+    expect(mapScanStateToOverlayState(state, CaptureType.selfie)).toBe(
+      UseSmileIDOverlayState.READY,
+    );
+  });
+
+  it("maps a finished state to CAPTURING", () => {
+    // CAPTURING is the yellow-solid state — the analyzer has emitted
+    // its captured artifacts and the orchestrator is about to call
+    // flush().
+    const state: ScanState = { type: ScanStateType.Finished };
+    expect(mapScanStateToOverlayState(state, CaptureType.selfie)).toBe(
+      UseSmileIDOverlayState.CAPTURING,
+    );
+  });
+
+  it("maps the headTurn state to HEAD_TURN", () => {
+    const state: ScanState = { type: ScanStateType.HeadTurn };
+    expect(mapScanStateToOverlayState(state, CaptureType.selfie)).toBe(
+      UseSmileIDOverlayState.HEAD_TURN,
+    );
+  });
+
+  it("maps timeout back to IDLE so the overlay returns to the gray pre-capture state", () => {
+    const state: ScanState = { type: ScanStateType.Timeout };
+    expect(mapScanStateToOverlayState(state, CaptureType.selfie)).toBe(
+      UseSmileIDOverlayState.IDLE,
+    );
+  });
+
+  describe("found + feedback (selfie)", () => {
+    const cases: Array<[string, UseSmileIDOverlayState]> = [
+      ["si_capture_too_close", UseSmileIDOverlayState.TOO_CLOSE],
+      ["si_capture_too_far", UseSmileIDOverlayState.TOO_FAR],
+      ["si_capture_multiple_faces", UseSmileIDOverlayState.MULTIPLE_FACES],
+      // `si_capture_center_face` is the key the native side actually
+      // emits for an off-centre face (the former
+      // `si_capture_face_not_centered` was never emitted).
+      ["si_capture_center_face", UseSmileIDOverlayState.FACE_NOT_CENTERED],
+      ["si_capture_low_light", UseSmileIDOverlayState.LOW_LIGHT],
+      ["si_capture_bright_light", UseSmileIDOverlayState.BRIGHT_LIGHT],
+      [
+        "si_capture_wrong_orientation",
+        UseSmileIDOverlayState.WRONG_ORIENTATION,
+      ],
+      ["si_capture_rotate_device", UseSmileIDOverlayState.WRONG_ORIENTATION],
+      ["si_capture_smile", UseSmileIDOverlayState.NOT_SMILING],
+      ["si_capture_move_left", UseSmileIDOverlayState.MOVE_LEFT],
+      ["si_capture_move_right", UseSmileIDOverlayState.MOVE_RIGHT],
+      ["si_capture_move_higher", UseSmileIDOverlayState.MOVE_UP],
+      ["si_capture_move_lower", UseSmileIDOverlayState.MOVE_DOWN],
+    ];
+
+    for (const [feedbackKey, expected] of cases) {
+      it(`maps found+${feedbackKey} to ${expected}`, () => {
+        const state: ScanState = {
+          type: ScanStateType.Found,
+          feedback: feedbackKey,
+        };
+        expect(mapScanStateToOverlayState(state, CaptureType.selfie)).toBe(
+          expected,
+        );
+      });
+    }
+
+    it("falls back to FACE_DETECTED when found has no feedback key", () => {
+      const state: ScanState = { type: ScanStateType.Found };
+      expect(mapScanStateToOverlayState(state, CaptureType.selfie)).toBe(
+        UseSmileIDOverlayState.FACE_DETECTED,
+      );
+    });
+
+    it("falls back to FACE_DETECTED on an unknown feedback key", () => {
+      // Forward-compat: a future native plugin might emit a new
+      // si_capture_* key the JS side hasn't been updated for. The
+      // overlay should stay alive (green-solid) rather than throwing
+      // or rendering an empty state.
+      const state: ScanState = {
+        type: ScanStateType.Found,
+        feedback: "si_capture_future_feedback_key",
+      };
+      expect(mapScanStateToOverlayState(state, CaptureType.selfie)).toBe(
+        UseSmileIDOverlayState.FACE_DETECTED,
+      );
+    });
+  });
+
+  describe("unsatisfied + reason (selfie)", () => {
+    it("uses the reason key to drive the orange-solid overlay", () => {
+      const state: ScanState = {
+        type: ScanStateType.Unsatisfied,
+        reason: "si_capture_too_close",
+      };
+      expect(mapScanStateToOverlayState(state, CaptureType.selfie)).toBe(
+        UseSmileIDOverlayState.TOO_CLOSE,
+      );
+    });
+
+    it("falls back to FACE_NOT_CENTERED on a missing reason key", () => {
+      const state: ScanState = { type: ScanStateType.Unsatisfied };
+      expect(mapScanStateToOverlayState(state, CaptureType.selfie)).toBe(
+        UseSmileIDOverlayState.FACE_NOT_CENTERED,
+      );
+    });
+  });
+
+  describe("document capture mappings", () => {
+    it("maps found+document key to DOCUMENT_READY by default", () => {
+      const state: ScanState = { type: ScanStateType.Found };
+      expect(mapScanStateToOverlayState(state, CaptureType.document)).toBe(
+        UseSmileIDOverlayState.DOCUMENT_READY,
+      );
+    });
+
+    it("maps the si_document_too_close key to DOCUMENT_TOO_CLOSE", () => {
+      const state: ScanState = {
+        type: ScanStateType.Found,
+        feedback: "si_document_too_close",
+      };
+      expect(mapScanStateToOverlayState(state, CaptureType.document)).toBe(
+        UseSmileIDOverlayState.DOCUMENT_TOO_CLOSE,
+      );
+    });
+
+    it("accepts the shared si_capture_too_close key for document flows", () => {
+      // The native side may emit either the document-specific
+      // si_document_* key or the shared si_capture_* one. Map both
+      // to the document overlay enum so the bottom-feedback bubble
+      // stays accurate either way.
+      const state: ScanState = {
+        type: ScanStateType.Found,
+        feedback: "si_capture_too_close",
+      };
+      expect(mapScanStateToOverlayState(state, CaptureType.document)).toBe(
+        UseSmileIDOverlayState.DOCUMENT_TOO_CLOSE,
+      );
+    });
+
+    it("maps unsatisfied+missing reason to DOCUMENT_NOT_CENTERED", () => {
+      const state: ScanState = { type: ScanStateType.Unsatisfied };
+      expect(mapScanStateToOverlayState(state, CaptureType.document)).toBe(
+        UseSmileIDOverlayState.DOCUMENT_NOT_CENTERED,
+      );
+    });
+
+    it("maps si_document_hold_still to DOCUMENT_HOLD_STILL", () => {
+      const state: ScanState = {
+        type: ScanStateType.Found,
+        feedback: "si_document_hold_still",
+      };
+      expect(mapScanStateToOverlayState(state, CaptureType.document)).toBe(
+        UseSmileIDOverlayState.DOCUMENT_HOLD_STILL,
+      );
+    });
+
+    it("maps the si_document_center key to DOCUMENT_NOT_CENTERED", () => {
+      // `si_document_center` is the key the native side actually emits
+      // for an off-centre document (the former `si_document_not_centered`
+      // was never emitted).
+      const state: ScanState = {
+        type: ScanStateType.Found,
+        feedback: "si_document_center",
+      };
+      expect(mapScanStateToOverlayState(state, CaptureType.document)).toBe(
+        UseSmileIDOverlayState.DOCUMENT_NOT_CENTERED,
+      );
+    });
+  });
+});