@microblink/blinkid-ux-manager 7.6.4 → 7.7.1

package/types/core/uxAnalyticsMappers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uxAnalyticsMappers.d.ts","sourceRoot":"","sources":["../../src/core/uxAnalyticsMappers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAEjE;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,OAAO,CAC3C,sBAAsB,EACtB,sBAAsB,CACvB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,uBAAuB,GAChC,eAAe,CAAC,kBAAkB,CAAC,CA4BrC"}

package/types/index.d.ts

@@ -7,14 +7,15 @@
  * This package includes feedback UI, localization support, and document scanning state management to create
  * an intuitive document scanning experience.
  */
+export type * from "@microblink/feedback-stabilizer";
+export type * from "@microblink/ux-common/hapticFeedback";
 export * from "./core/blinkid-ui-state";
-export * from "./core/BlinkIdUxManager";
+export type { BlinkIdProcessingError } from "./core/BlinkIdProcessingError";
+export type { BlinkIdUxManager } from "./core/BlinkIdUxManager";
+export * from "./core/createBlinkIdUxManager";
+export type { DocumentClassFilter } from "./core/DocumentClassFilter";
 export * from "./ui/createBlinkIdFeedbackUi";
 export type { LocaleRecord, LocalizationStrings, } from "./ui/LocalizationContext";
-export type { DocumentClassFilter } from "./core/DocumentClassFilter";
-export type * from "@microblink/ux-common/hapticFeedback";
-export type * from "@microblink/feedback-stabilizer";
-export type { BlinkIdProcessingError } from "./core/BlinkIdProcessingError";
 /**
  * The global interface.
  *

package/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;GAKG;AAEH,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,8BAA8B,CAAC;AAC7C,YAAY,EACV,YAAY,EACZ,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEtE,mBAAmB,sCAAsC,CAAC;AAC1D,mBAAmB,iCAAiC,CAAC;AACrD,YAAY,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAE5E;;;;GAIG;AACH,QAAA,MAAM,UAAU,eAAW,CAAC;AAE5B;;GAEG;AACH,OAAO,CAAC,MAAM,CAAC;IAEb,IAAI,sBAAsB,EAAE,OAAO,UAAU,CAAC;CAC/C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;GAKG;AAEH,mBAAmB,iCAAiC,CAAC;AACrD,mBAAmB,sCAAsC,CAAC;AAC1D,cAAc,yBAAyB,CAAC;AACxC,YAAY,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAC5E,YAAY,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,cAAc,+BAA+B,CAAC;AAC9C,YAAY,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,cAAc,8BAA8B,CAAC;AAC7C,YAAY,EACV,YAAY,EACZ,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAElC;;;;GAIG;AACH,QAAA,MAAM,UAAU,eAAW,CAAC;AAE5B;;GAEG;AACH,OAAO,CAAC,MAAM,CAAC;IAEb,IAAI,sBAAsB,EAAE,OAAO,UAAU,CAAC;CAC/C"}

package/types/index.rollup.d.ts

@@ -1,14 +1,53 @@
+import { AnalyticService } from '@microblink/analytics/AnalyticService';
 import { BlinkIdScanningResult } from '@microblink/blinkid-core';
 import { BlinkIdSessionSettings } from '@microblink/blinkid-core';
-import type { CameraManager } from '@microblink/camera-manager';
+import { CameraManager } from '@microblink/camera-manager';
 import { CameraManagerComponent } from '@microblink/camera-manager';
+import { DeviceInfo } from '@microblink/blinkid-core';
 import { DocumentClassInfo } from '@microblink/blinkid-core';
 import { InputImageAnalysisResult } from '@microblink/blinkid-core';
 import { ProcessResultWithBuffer } from '@microblink/blinkid-core';
 import { RemoteScanningSession } from '@microblink/blinkid-core';
 import { ResultCompleteness } from '@microblink/blinkid-core';
 import { ScanningSettings } from '@microblink/blinkid-core';
-import { StringKeyOf } from 'type-fest';
+
+/**
+ * Union type of all page transition state keys.
+ *
+ * @see {@link blinkIdPageTransitionKeys} for detailed documentation on each state
+ */
+export declare type BlinkIdPageTransitionKey = (typeof blinkIdPageTransitionKeys)[number];
+
+/**
+ * Page transition state keys for BlinkID UI.
+ *
+ * @remarks
+ * These states display transition animations and instructions between scanning
+ * different document pages or sides. They are automatically triggered after
+ * successfully capturing a page (`PAGE_CAPTURED`) and cannot be manually set.
+ *
+ * Each transition state corresponds to a specific document type and guides the
+ * user to position the document for the next scan:
+ * - `FLIP_CARD` - Instructs user to flip ID card to scan the back side
+ * - `MOVE_LAST_PAGE` - Instructs user to move to passport's last page (barcode)
+ * - `MOVE_TOP` - Instructs user to rotate passport to top orientation (0°)
+ * - `MOVE_RIGHT` - Instructs user to rotate passport 90° clockwise
+ * - `MOVE_LEFT` - Instructs user to rotate passport 90° counter-clockwise
+ *
+ * **Automatic flow:**
+ * After a transition animation completes, the UI automatically advances to the
+ * corresponding intro state to begin scanning the next page:
+ * - `FLIP_CARD` → `INTRO_BACK_PAGE`
+ * - `MOVE_LAST_PAGE` → `INTRO_LAST_PAGE`
+ * - `MOVE_TOP` → `INTRO_TOP_PAGE`
+ * - `MOVE_RIGHT` → `INTRO_RIGHT_PAGE`
+ * - `MOVE_LEFT` → `INTRO_LEFT_PAGE`
+ *
+ * @see {@link BlinkIdPageTransitionKey} for the union type of these keys
+ * @see {@link getChainedUiStateKey} for the automatic state transition logic
+ * @see {@link blinkIdUiIntroStateKeys} for the intro states that follow transitions
+ */
+export declare const blinkIdPageTransitionKeys: readonly ["FLIP_CARD", "MOVE_TOP", "MOVE_LEFT", "MOVE_RIGHT", "MOVE_LAST_PAGE"];
 
 /**
  * Copyright (c) 2026 Microblink Ltd. All rights reserved.
@@ -17,13 +56,70 @@ import { StringKeyOf } from 'type-fest';
  * BlinkID processing error. These errors are usually unrecoverable and require
  * the user to retry the scanning process.
  */
-export declare type BlinkIdProcessingError = "timeout" | "unsupported_document" | "unknown";
+export declare type BlinkIdProcessingError = "timeout" | "unsupported_document" | "result_retrieval_failed" | "unknown";
 
 /**
  * The type of reticle to display.
  */
 export declare type BlinkIdReticleType = "searching" | "processing" | "error" | "done" | "flip" | "move_top" | "move_left" | "move_right";
 
+export declare type BlinkIdUiErrorStateKey = (typeof blinkIdUiErrorStateKeys)[number];
+
+/**
+ * The error states for BlinkID. Mappable from `ProcessResult`.
+ */
+export declare const blinkIdUiErrorStateKeys: readonly ["FRONT_PAGE_NOT_IN_FRAME", "BACK_PAGE_NOT_IN_FRAME", "DATA_PAGE_NOT_IN_FRAME", "TOP_PAGE_NOT_IN_FRAME", "LEFT_PAGE_NOT_IN_FRAME", "RIGHT_PAGE_NOT_IN_FRAME", "LAST_PAGE_NOT_IN_FRAME", "BARCODE_NOT_IN_FRAME", "DOCUMENT_FRAMING_CAMERA_TOO_FAR", "DOCUMENT_FRAMING_CAMERA_TOO_CLOSE", "DOCUMENT_FRAMING_CAMERA_ANGLE_TOO_STEEP", "DOCUMENT_TOO_CLOSE_TO_FRAME_EDGE", "BLUR_DETECTED", "GLARE_DETECTED", "TOO_DARK", "TOO_BRIGHT", "OCCLUDED", "FACE_PHOTO_OCCLUDED", "WRONG_SIDE", "WRONG_TOP_PAGE", "WRONG_LEFT_PAGE", "WRONG_RIGHT_PAGE", "WRONG_LAST_PAGE", "UNSUPPORTED_DOCUMENT"];
+
+/**
+ * Union type of all intro state keys.
+ *
+ * @see {@link blinkIdUiIntroStateKeys} for detailed documentation on each state
+ */
+export declare type BlinkIdUiIntroStateKey = (typeof blinkIdUiIntroStateKeys)[number];
+
+/**
+ * Intro state keys for BlinkID UI.
+ *
+ * @remarks
+ * These states display introductory screens that guide users to scan the correct
+ * side or page of their document. Most intro states are automatically reached
+ * during the scanning flow, but `INTRO_DATA_PAGE` requires manual initialization.
+ *
+ * **Default behavior:**
+ * The UX manager defaults to `INTRO_FRONT_PAGE`, assuming users will scan
+ * non-passport documents (ID cards, driver's licenses, etc.).
+ *
+ * **Automatically reachable states:**
+ * After capturing a page, the flow automatically transitions through appropriate
+ * intro states:
+ * - `INTRO_BACK_PAGE` - After flipping an ID card (`FLIP_CARD`)
+ * - `INTRO_TOP_PAGE` - After moving to passport top page (`MOVE_TOP`)
+ * - `INTRO_LEFT_PAGE` - After moving to passport left page (`MOVE_LEFT`)
+ * - `INTRO_RIGHT_PAGE` - After moving to passport right page (`MOVE_RIGHT`)
+ * - `INTRO_LAST_PAGE` - After moving to passport barcode page (`MOVE_LAST_PAGE`)
+ *
+ * **Manual initialization required:**
+ * - `INTRO_DATA_PAGE` - Only reachable by overriding the UX manager initial
+ *   state. Use this when restricting scanning to passport documents only,
+ *   as the SDK assumes non-passport documents by default.
+ *
+ * @example
+ * ```typescript
+ * // Limit scanning to passport documents only
+ * const uxManager = new BlinkIdUxManager(cameraManager, session);
+ * uxManager.setInitialUiStateKey("INTRO_DATA_PAGE", true);
+ * ```
+ *
+ * @see {@link BlinkIdUiIntroStateKey} for the union type of these keys
+ * @see {@link getChainedUiStateKey} for the automatic state transition logic
+ */
+export declare const blinkIdUiIntroStateKeys: readonly ["INTRO_FRONT_PAGE", "INTRO_BACK_PAGE", "INTRO_DATA_PAGE", "INTRO_TOP_PAGE", "INTRO_LEFT_PAGE", "INTRO_RIGHT_PAGE", "INTRO_LAST_PAGE"];
+
+/**
+ * These keys are directly mappable from a `ProcessResult`
+ */
+export declare type BlinkIdUiMappableKey = BlinkIdUiErrorStateKey | BlinkIdUiStepSuccessKey | "PROCESSING_BARCODE";
+
 /**
  * The UI state of BlinkID.
  */
@@ -32,7 +128,7 @@ export declare type BlinkIdUiState = BlinkIdUiStateMap[keyof BlinkIdUiStateMap];
 /**
  * The key of the UI state.
  */
-export declare type BlinkIdUiStateKey = "FLIP_CARD" | "DOCUMENT_CAPTURED" | "SENSING_FRONT" | "SENSING_BACK" | "SENSING_DATA_PAGE" | "SENSING_TOP_PAGE" | "SENSING_LEFT_PAGE" | "SENSING_RIGHT_PAGE" | "SENSING_LAST_PAGE" | "MOVE_TOP" | "MOVE_LEFT" | "MOVE_RIGHT" | "MOVE_LAST_PAGE" | "DOCUMENT_FRAMING_CAMERA_TOO_FAR" | "DOCUMENT_FRAMING_CAMERA_TOO_CLOSE" | "DOCUMENT_FRAMING_CAMERA_ANGLE_TOO_STEEP" | "DOCUMENT_TOO_CLOSE_TO_FRAME_EDGE" | "BLUR_DETECTED" | "GLARE_DETECTED" | "TOO_DARK" | "TOO_BRIGHT" | "OCCLUDED" | "FACE_PHOTO_OCCLUDED" | "UNSUPPORTED_DOCUMENT" | "SCAN_BARCODE" | "WRONG_TOP_PAGE" | "WRONG_LEFT_PAGE" | "WRONG_RIGHT_PAGE" | "WRONG_LAST_PAGE" | "WRONG_SIDE";
+export declare type BlinkIdUiStateKey = BlinkIdUiIntroStateKey | BlinkIdPageTransitionKey | BlinkIdUiMappableKey;
 
 /**
  * Extended UI state for BlinkID.
@@ -53,6 +149,13 @@ export declare type BlinkIdUiStateMap = {
  */
 export declare const blinkIdUiStateMap: BlinkIdUiStateMap;
 
+export declare type BlinkIdUiStepSuccessKey = (typeof blinkIdUiStepSuccessKeys)[number];
+
+/**
+ * These keys represent successful steps in the BlinkID scanning process.
+ */
+export declare const blinkIdUiStepSuccessKeys: readonly ["PAGE_CAPTURED", "DOCUMENT_CAPTURED"];
+
 /**
  * The BlinkIdUxManager class. This is the main class that manages the UX of
  * the BlinkID SDK. It is responsible for handling the UI state, the timeout,
@@ -61,48 +164,60 @@ export declare const blinkIdUiStateMap: BlinkIdUiStateMap;
 export declare class BlinkIdUxManager {
     #private;
     /** The camera manager. */
-    cameraManager: CameraManager;
+    readonly cameraManager: CameraManager;
     /** The scanning session. */
-    scanningSession: RemoteScanningSession;
-    /** Whether the demo overlay should be shown. */
-    showDemoOverlay: boolean;
-    /** Whether the production overlay should be shown. */
-    showProductionOverlay: boolean;
-    /** The current UI state. */
-    uiState: BlinkIdUiState;
-    /** The raw UI state key. */
-    rawUiStateKey: BlinkIdUiStateKey;
-    /** The feedback stabilizer. */
-    feedbackStabilizer: FeedbackStabilizer<typeof blinkIdUiStateMap>;
-    /** The session settings. */
-    sessionSettings: BlinkIdSessionSettings;
+    readonly scanningSession: RemoteScanningSession;
+    /**
+     * The current UI state. Updated internally by the RAF update loop.
+     * Read externally once at UI mount to seed the initial Solid signal value;
+     * subsequent updates are delivered via {@link addOnUiStateChangedCallback}.
+     */
+    get uiState(): BlinkIdUiState;
+    /**
+     * The feedback stabilizer. Public to allow UI components to read scores,
+     * event queues, and call restartCurrentStateTimer() for help-tooltip resets.
+     */
+    readonly feedbackStabilizer: FeedbackStabilizer<BlinkIdUiStateMap>;
+    /** The session settings. Populated asynchronously from the scanning session. */
+    readonly sessionSettings: BlinkIdSessionSettings;
+    /** Whether the demo overlay should be shown. Populated asynchronously from the scanning session. */
+    readonly showDemoOverlay: boolean;
+    /** Whether the production overlay should be shown. Populated asynchronously from the scanning session. */
+    readonly showProductionOverlay: boolean;
+    /** The device info. */
+    readonly deviceInfo: DeviceInfo;
     /**
      * The constructor for the BlinkIdUxManager class.
      *
      * @param cameraManager - The camera manager.
      * @param scanningSession - The scanning session.
+     * @param options - Optional manager configuration.
      */
-    constructor(cameraManager: CameraManager, scanningSession: RemoteScanningSession);
+    constructor(cameraManager: CameraManager, scanningSession: RemoteScanningSession, options: BlinkIdUxManagerOptions | undefined, sessionSettings: BlinkIdSessionSettings, showDemoOverlay: boolean, showProductionOverlay: boolean, deviceInfo: DeviceInfo);
+    /** The currently applied UI state key. */
+    get uiStateKey(): BlinkIdUiStateKey;
+    /** Latest mapped candidate key before stabilization. */
+    get mappedUiStateKey(): BlinkIdUiStateKey;
     /**
-     * Indicates whether the UI should display the demo overlay. Controlled by the
-     * license property.
+     * @deprecated Use `mappedUiStateKey` (internal/debug) or `uiStateKey` (displayed state).
      */
-    getShowDemoOverlay(): boolean;
-    /**
-     * Indicates whether the UI should display the production overlay. Controlled by
-     * the license property.
-     */
-    getShowProductionOverlay(): boolean;
+    get rawUiStateKey(): BlinkIdUiStateKey;
+    startUiUpdateLoop(): void;
+    stopUiUpdateLoop(): void;
     /**
      * Returns the timeout duration in ms. Null if timeout won't be triggered ever.
      */
     getTimeoutDuration(): number | null;
     /**
      * Returns the time in ms before the help tooltip is shown. Null if tooltip won't be auto shown.
+     *
+     * @deprecated This option will be removed in a future release. Use `helpTooltipShowDelay` in `FeedbackUiOptions` instead.
      */
     getHelpTooltipShowDelay(): number | null;
     /**
      * Returns the time in ms before the help tooltip is hidden. Null if tooltip won't be auto hidden.
+     *
+     * @deprecated This option will be removed in a future release. Use `helpTooltipHideDelay` in `FeedbackUiOptions` instead.
      */
     getHelpTooltipHideDelay(): number | null;
     /**
@@ -129,6 +244,12 @@ export declare class BlinkIdUxManager {
      * @returns true if haptic feedback is supported
      */
     isHapticFeedbackSupported(): boolean;
+    /**
+     * Gets the analytics service for tracking UX events.
+     *
+     * @returns The UX analytics service
+     */
+    get analytics(): AnalyticService;
     /**
      * Adds a callback function to be executed when the UI state changes.
      *
@@ -250,6 +371,8 @@ export declare class BlinkIdUxManager {
      * shown. If null, tooltip won't be auto shown.
      * @throws {Error} Throws an error if duration is less than or equal to 0 when
      * not null.
+     *
+     * @deprecated This option will be removed in a future release. Use `helpTooltipShowDelay` in `FeedbackUiOptions` instead.
      */
     setHelpTooltipShowDelay(duration: number | null): void;
     /**
@@ -260,25 +383,31 @@ export declare class BlinkIdUxManager {
      * hidden. If null, tooltip won't be auto hidden.
      * @throws {Error} Throws an error if duration is less than or equal to 0 when
      * not null.
+     *
+     * @deprecated This option will be removed in a future release. Use `helpTooltipHideDelay` in `FeedbackUiOptions` instead.
      */
     setHelpTooltipHideDelay(duration: number | null): void;
+    /**
+     * Returns the initial UI state key used when resetting UX state.
+     */
+    getInitialUiStateKey(): BlinkIdUiStateKey;
+    /**
+     * Overrides the initial UI state key.
+     *
+     * @param uiStateKey - The UI state key to use as manager initial state.
+     * @param applyImmediately - If true, immediately applies and emits this state.
+     */
+    setInitialUiStateKey(uiStateKey: BlinkIdUiStateKey, applyImmediately?: boolean): void;
     /**
      * Clears the scanning session timeout.
      */
-    clearScanTimeout: () => void;
+    clearScanTimeout(): void;
     /**
      * Gets the result from the scanning session.
      *
-     * @param deleteSession - Whether to delete the session after getting the result. Note that
-     * it is not possible to get the result a second time after the document has been fully captured,
-     * so in this case we should delete the scanning session since it is no longer needed.
      * @returns The result.
      */
-    getSessionResult(deleteSession?: boolean): Promise<BlinkIdScanningResult>;
-    /**
-     * Safely deletes the scanning session.
-     */
-    safelyDeleteScanningSession(): Promise<void>;
+    getSessionResult(): Promise<BlinkIdScanningResult>;
     /**
      * Resets the scanning session.
      *
@@ -293,19 +422,44 @@ export declare class BlinkIdUxManager {
      * Does not reset the camera manager or the scanning session.
      */
     reset(): void;
+    /**
+     * Fully tears down the BlinkIdUxManager. Stops frame processing, cancels the
+     * scan timeout, removes all subscriptions and the RAF loop, and clears all
+     * registered callbacks. Should be called when the manager is no longer needed.
+     *
+     * Does not stop the camera stream or delete the scanning session.
+     */
+    destroy(): void;
 }
 
+export declare type BlinkIdUxManagerOptions = {
+    /**
+     * Initial UI state key used by the manager/stabilizer reset flow.
+     * Defaults to `INTRO_FRONT_PAGE`.
+     */
+    initialUiStateKey?: BlinkIdUiStateKey;
+};
+
 /**
  * Creates the BlinkID feedback UI.
  *
  * @param blinkIdUxManager - The BlinkID Ux Manager.
  * @param cameraManagerComponent - The Camera Manager Component.
- * @param feedbackUiOptions - The feedback UI options for the createBlinkIdFeedbackUi function.
+ * @param options - The feedback UI options for the createBlinkIdFeedbackUi function
  *
  * @returns The function to unmount the feedback UI.
  */
 export declare function createBlinkIdFeedbackUi(blinkIdUxManager: BlinkIdUxManager, cameraManagerComponent: CameraManagerComponent, feedbackUiOptions: Partial<FeedbackUiOptions>): () => void;
 
+/**
+ * Creates a BlinkIdUxManager.
+ *
+ * @param cameraManager - The camera manager.
+ * @param scanningSession - The scanning session.
+ * @returns The BlinkIdUxManager instance.
+ */
+export declare const createBlinkIdUxManager: (cameraManager: CameraManager, scanningSession: RemoteScanningSession, options?: BlinkIdUxManagerOptions) => Promise<BlinkIdUxManager>;
+
 /**
  * Localization strings for en.
  */
@@ -319,7 +473,7 @@ declare const _default: {
     readonly document_not_recognized: "Document not recognized";
     readonly document_not_recognized_details: "Scan the front side of a supported document.";
     readonly document_scanned: "Success! Document scanned";
-    readonly document_too_close_to_edge: "Move the document from the edge";
+    readonly document_too_close_to_edge: "Move farther";
     readonly face_photo_not_fully_visible: "Keep face photo fully visible";
     readonly flip_document: "Flip the document";
     readonly flip_to_back_side: "Flip to the back side";
@@ -327,6 +481,9 @@ declare const _default: {
     readonly glare_detected: "Tilt or move document to remove reflection";
     readonly help_aria_label: "Help";
     readonly help_modal_back_btn: "Back";
+    readonly help_modal_blur_details_desktop: "Try to keep the device and document still while scanning. Moving either can blur the image and make data on the document unreadable.";
+    readonly help_modal_camera_lens_details: "Check your camera lens for smudges or dust. A dirty lens causes the final image to blur, making the document details unreadable and preventing successful scan of the data.";
+    readonly help_modal_camera_lens_title: "Clean your camera lens";
     readonly help_modal_details_1: "Make sure you aren’t covering parts of the document with a finger, including the bottom lines. Also, watch out for hologram reflections that go over the document fields.";
     readonly help_modal_details_2: "Avoid direct harsh light because it reflects from the document and can make parts of the document unreadable. If you can’t read data on the document, it won’t be visible to the camera either.";
     readonly help_modal_details_3: "Try to keep the phone and document still while scanning. Moving either can blur the image and make data on the document unreadable.";
@@ -336,6 +493,8 @@ declare const _default: {
     readonly help_modal_title_2: "Watch out for harsh light";
     readonly help_modal_title_3: "Keep still while scanning";
     readonly help_tooltip: "Need help?";
+    readonly keep_document_parallel: "Keep document parallel with screen";
+    readonly keep_document_still: "Keep document and device still";
     readonly move_closer: "Move closer";
     readonly move_farther: "Move farther";
     readonly move_left: "Move to the page on the left";
@@ -344,7 +503,10 @@ declare const _default: {
     readonly occluded: "Keep the document fully visible";
     readonly onboarding_modal_btn: "Start scanning";
     readonly onboarding_modal_details: "Make sure you keep the document well lit. All document fields should be visible on the camera screen.";
+    readonly onboarding_modal_details_desktop: "Make sure you keep your camera lens clean and the document well lit. All document fields should be visible on the camera screen.";
     readonly onboarding_modal_title: "Keep all the details visible";
+    readonly onboarding_modal_title_desktop: "Get ready to scan";
+    readonly resume_scanning: "Resume scanning";
     readonly scan_data_page: "Scan the data page of the document";
     readonly scan_last_page_barcode: "Scan barcode from the last page";
     readonly scan_left_page: "Scan the left page";
@@ -355,6 +517,9 @@ declare const _default: {
     readonly scan_top_page: "Scan the top page";
     readonly scan_unsuccessful: "Scan unsuccessful";
     readonly scan_unsuccessful_details: "Unable to read the document. Please try again.";
+    readonly scanning_help: "Scanning help";
+    readonly scanning_instructions: "Scanning Instructions";
+    readonly scanning_screen: "Document scanning screen";
     readonly too_bright: "Move to spot with less lighting";
     readonly too_dark: "Move to brighter spot";
     readonly wrong_left: "Move to the left page";
@@ -378,9 +543,6 @@ declare const _default: {
  */
 export declare type DocumentClassFilter = (documentClassInfo: DocumentClassInfo) => boolean;
 
-/** The error UI state keys. */
-export declare const errorUiStateKeys: BlinkIdUiStateKey[];
-
 /**
  * FeedbackStabilizer provides UI state management with temporal smoothing.
  *
@@ -399,7 +561,6 @@ export declare class FeedbackStabilizer<SdkSpecificStateMap extends UiStateMap>
     private uiStateMap;
     /** Time window (in ms) for considering UI state events. */
     private timeWindow;
-    /** The decay rate. */
     /** Rate at which event weights decay over time */
     private decayRate;
     /** Queue of regular UI state events within the time window */
@@ -419,13 +580,19 @@ export declare class FeedbackStabilizer<SdkSpecificStateMap extends UiStateMap>
      *
      * @returns The currently active UI state configuration.
      */
-    get currentState(): SdkSpecificStateMap[`${Extract<keyof SdkSpecificStateMap, string | number>}`];
+    get currentState(): SdkSpecificStateMap[StateKey<SdkSpecificStateMap>];
     /**
      * Gets a copy of the current event queue for debugging.
      *
      * @returns A copy of the current event queue.
      */
-    getEventQueue(): UiStateEvent[];
+    getEventQueue(): UiStateEvent<StateKey<SdkSpecificStateMap>>[];
+    /**
+     * Gets a copy of the single event queue for debugging.
+     *
+     * @returns A copy of the current event queue.
+     */
+    getSingleEventQueue(): UiStateEvent<StateKey<SdkSpecificStateMap>>[];
     /**
      * Gets the current summed scores for each state.
      *
@@ -452,19 +619,58 @@ export declare class FeedbackStabilizer<SdkSpecificStateMap extends UiStateMap>
      * @param timeWindow - Optional custom time window (in ms) for state averaging
      * @param decayRate - Optional custom decay rate for event weights
      */
-    constructor(uiStateMap: SdkSpecificStateMap, initialKey: StringKeyOf<SdkSpecificStateMap>, timeWindow?: number, decayRate?: number);
+    constructor(uiStateMap: SdkSpecificStateMap, initialKey: StateKey<SdkSpecificStateMap>, timeWindow?: number, decayRate?: number);
     /**
      * Resets the stabilizer to its initial state.
      *
-     * @returns The initial state.
+     * @param currentKey - resets the stabilizer with a different key
+     * than the one it was initialized with. Does not mutate `this.initialKey`
      */
-    reset(): void;
+    reset(currentKey?: StateKey<SdkSpecificStateMap>): void;
+    /**
+     * Restarts the minimum-duration timer for the current state.
+     * Useful when a state should be timed from an external lifecycle point
+     * (e.g. actual capture start) instead of construction/reset time.
+     */
+    restartCurrentStateTimer(): void;
     /**
      * Checks if enough time has passed to show a new UI state
      *
      * @returns true if the current state's minimum duration has elapsed
      */
     canShowNewUiState: () => boolean;
+    /**
+     * Retrieves the remaining time for the current state to satisfy its minimum duration.
+     * @returns Remaining time in milliseconds.
+     */
+    getRemainingDuration(): number;
+    /**
+     * Creates a UI state event and enqueues it for later processing.
+     *
+     * Regular states go to `eventQueue` and take part in weighted stabilization.
+     * States marked with `singleEmit` go to `singleEventQueue` and are emitted
+     * once the current state satisfies its minimum duration.
+     *
+     * @param incomingUiStateKey - Key of the incoming UI state event.
+     */
+    private enqueueEvent;
+    /**
+     * Enqueues a new UI state event to be considered on the next `tick()`.
+     *
+     * @param incomingUiStateKey - Key of the new UI state event
+     */
+    ingest(incomingUiStateKey: StateKey<SdkSpecificStateMap>): void;
+    /**
+     * Advances stabilizer time and returns the state that should be displayed.
+     *
+     * This method:
+     * 1. Handles single-emit events that bypass normal stabilization
+     * 2. Maintains a time-windowed queue of regular events
+     * 3. Applies temporal averaging with decay to determine the winning state
+     *
+     * @returns The UI state that should be displayed.
+     */
+    tick(): SdkSpecificStateMap[StateKey<SdkSpecificStateMap>];
     /**
      * Processes a new UI state event and determines the state to display.
      *
@@ -476,7 +682,7 @@ export declare class FeedbackStabilizer<SdkSpecificStateMap extends UiStateMap>
      * @param incomingUiStateKey - Key of the new UI state event
      * @returns The UI state that should be displayed.
      */
-    getNewUiState(incomingUiStateKey: StringKeyOf<SdkSpecificStateMap>): SdkSpecificStateMap[StringKeyOf<SdkSpecificStateMap>];
+    getNewUiState(incomingUiStateKey: StateKey<SdkSpecificStateMap>): SdkSpecificStateMap[StateKey<SdkSpecificStateMap>];
 }
 
 /**
@@ -507,11 +713,24 @@ export declare type FeedbackUiOptions = {
      */
     showHelpButton?: boolean;
     /**
-     * The timeout for the help tooltip.
+     * The timeout for the help tooltip in ms.
      *
      * @defaultValue 3000
+     * @deprecated This option will be removed in a future release. Use `helpTooltipShowDelay` instead.
      */
     showHelpTooltipTimeout?: number;
+    /**
+     * Time in ms before the help tooltip is shown. If null, tooltip won't be auto shown.
+     *
+     * @defaultValue 5000
+     */
+    helpTooltipShowDelay?: number | null;
+    /**
+     * Time in ms before the help tooltip is hidden. If null, tooltip won't be auto hidden.
+     *
+     * @defaultValue 5000
+     */
+    helpTooltipHideDelay?: number | null;
     /**
      * If set to `true`, the document filtered modal will be shown.
      *
@@ -532,11 +751,6 @@ export declare type FeedbackUiOptions = {
     showUnsupportedDocumentModal?: boolean;
 };
 
-/**
- * The states that are captured when the first side is captured.
- */
-export declare const firstSideCapturedUiStateKeys: BlinkIdUiStateKey[];
-
 /**
  * Determines the appropriate UI state key based on the current frame processing
  * result and scanning settings.
@@ -551,7 +765,7 @@ export declare const firstSideCapturedUiStateKeys: BlinkIdUiStateKey[];
  * selection.
  * @returns The UI state key representing what should be shown to the user.
  */
-export declare function getUiStateKey(frameProcessResult: PartialProcessResult, settings?: Partial<ScanningSettings>): BlinkIdUiStateKey;
+export declare function getUiStateKey(frameProcessResult: PartialProcessResult, settings?: Partial<ScanningSettings>): BlinkIdUiMappableKey | undefined;
 
 /**
  * Mapping of haptic feedback types to their durations.
@@ -634,13 +848,21 @@ export declare type PartialProcessResult = {
     resultCompleteness: Partial<ResultCompleteness>;
 };
 
+/** Helper type to extract string keys from a state map */
+declare type StateKey<T extends UiStateMap> = keyof T & string;
+
+/**
+ * Copyright (c) 2026 Microblink Ltd. All rights reserved.
+ */
 /**
  * Represents a UI state configuration with timing and weight parameters.
  * Used to define how different UI states should behave in the stabilization process.
+ *
+ * @typeParam K - The specific key type for this UI state
  */
-export declare type UiState = {
+export declare type UiState<K extends string = string> = {
     /** Unique identifier for the UI state */
-    key: string;
+    key: K;
     /** Minimum duration (in milliseconds) this state should be displayed */
     minDuration: number;
     /**
@@ -658,10 +880,12 @@ export declare type UiState = {
 /**
  * Represents a UI state event in the stabilization queue.
  * These events are processed to determine which UI state should be displayed.
+ *
+ * @typeParam K - The key type for this event, matching a UI state key
  */
-export declare type UiStateEvent = {
+export declare type UiStateEvent<K extends string = string> = {
     /** Identifier matching a UI state key */
-    key: string;
+    key: K;
     /** High-resolution timestamp when the event occurred */
     timeStamp: DOMHighResTimeStamp;
     /** Current weight of this event in the stabilization process */
@@ -676,6 +900,8 @@ export declare type UiStateEvent = {
 /**
  * Maps state keys to their corresponding UI state configurations.
  */
-export declare type UiStateMap = Record<string, UiState>;
+export declare type UiStateMap = {
+    [K in string]: UiState<K>;
+};
 
 export { }

package/types/ui/BlinkIdFeedbackUi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BlinkIdFeedbackUi.d.ts","sourceRoot":"","sources":["../../src/ui/BlinkIdFeedbackUi.tsx"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAe1C,OAAO,EAEL,mBAAmB,EAEpB,MAAM,uBAAuB,CAAC;AAI/B,OAAO,iBAAiB,CAAC;AAazB;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,CAAC;IACxC,YAAY,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAC7C,CAqLA,CAAC"}
+{"version":3,"file":"BlinkIdFeedbackUi.d.ts","sourceRoot":"","sources":["../../src/ui/BlinkIdFeedbackUi.tsx"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAkB1C,OAAO,EAEL,mBAAmB,EAEpB,MAAM,uBAAuB,CAAC;AAI/B,OAAO,iBAAiB,CAAC;AASzB;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,CAAC;IACxC,YAAY,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAC7C,CA6NA,CAAC"}

package/types/ui/BlinkIdUiStoreContext.d.ts

@@ -9,7 +9,7 @@ import type { BlinkIdUxManager } from "../core/BlinkIdUxManager";
 /**
  * The BlinkIdUiStore type.
  */
-export type BlinkIdUiStore = {
+type BlinkIdUiStore = {
     /**
      * The BlinkIdUxManager instance.
      */
@@ -31,9 +31,13 @@ export type BlinkIdUiStore = {
      */
     showOnboardingGuide?: boolean;
     /**
-     * The timeout for the help tooltip.
+     * Time in ms before the help tooltip is shown. If null, tooltip won't be auto shown.
      */
-    showHelpTooltipTimeout?: number;
+    helpTooltipShowDelay?: number | null;
+    /**
+     * Time in ms before the help tooltip is hidden. If null, tooltip won't be auto hidden.
+     */
+    helpTooltipHideDelay?: number | null;
     /**
      * Whether the help modal should be shown.
      */
@@ -77,7 +81,8 @@ export declare const BlinkIdUiStoreProvider: ParentComponent<{
     cameraManagerComponent: CameraManagerComponent;
     showOnboardingGuide: boolean;
     showHelpButton: boolean;
-    showHelpTooltipTimeout: number;
+    helpTooltipShowDelay: number | null;
+    helpTooltipHideDelay: number | null;
     showDocumentFilteredModal: boolean;
     showTimeoutModal: boolean;
     showUnsupportedDocumentModal: boolean;