@microblink/blinkid-ux-manager 7.8.0 → 8000.0.0

package/README.md

@@ -9,6 +9,7 @@ This package provides user experience management and feedback UI for the BlinkID
 - **Haptic Feedback:** Built-in haptic feedback support for enhanced user experience on mobile devices
 - **Document Filtering:** Advanced document class filtering capabilities
 - **Timeout Management:** Configurable scanning timeouts with automatic state management
+- **Progress Callbacks:** Live progress snapshots for debug overlays and custom tooling
 - **Localization Support:** Multi-language support with customizable strings
 - **Explicit Teardown:** `destroy()` method for deterministic resource cleanup
 - **UI State Inspection:** `uiStateKey` (stabilized, visible state) and `mappedUiStateKey` (latest raw candidate before stabilization) getters
@@ -20,6 +21,10 @@ This package provides user experience management and feedback UI for the BlinkID
 - Includes haptic feedback system for mobile devices.
 - Used by [`@microblink/blinkid`](https://www.npmjs.com/package/@microblink/blinkid) and can be used directly for custom UI integrations.
 
+## Migration from v7 to v8000
+
+For breaking changes and upgrade steps, see the [BlinkID v8000 migration guide](https://docs.microblink.com/blinkid/migration-v8000).
+
 ## Installation
 
 Install from npm using your preferred package manager:
@@ -104,6 +109,133 @@ const uxManager = await createBlinkIdUxManager(cameraManager, scanningSession);
 uxManager.destroy();
 ```
 
+### Configuring Scan Timeouts
+
+BlinkID uses three timeout windows during capture:
+
+- `inactivityTimeoutMs` restarts when the stabilized BlinkID UI state changes
+- `scanStepTimeoutMs` limits the total active capture time for the current scan step
+- `partiallySupportedBarcodeResolveTimeoutMs` resolves a barcode step after BlinkID reports a barcode whose parsing is not supported
+
+When the stabilized UI state is `PROCESSING_BARCODE` (the visible "scan the
+barcode" step), BlinkID suppresses the inactivity timeout and starts that
+barcode step with a fresh `scanStepTimeoutMs` window.
+
+You can override them when creating the manager:
+
+```javascript
+const uxManager = await createBlinkIdUxManager(cameraManager, scanningSession, {
+  timeoutConfiguration: {
+    inactivityTimeoutMs: 15000,
+    scanStepTimeoutMs: 90000,
+    partiallySupportedBarcodeResolveTimeoutMs: 8000,
+  },
+});
+```
+
+Set any timeout to `null` to disable it:
+
+```javascript
+const uxManager = await createBlinkIdUxManager(cameraManager, scanningSession, {
+  timeoutConfiguration: {
+    inactivityTimeoutMs: null,
+    scanStepTimeoutMs: 90000,
+    partiallySupportedBarcodeResolveTimeoutMs: null,
+  },
+});
+```
+
+You can also inspect or update the active configuration later:
+
+```javascript
+uxManager.getTimeoutConfiguration();
+uxManager.setTimeoutConfiguration({
+  inactivityTimeoutMs: 20000,
+});
+```
+
+### Observing Processed Frames
+
+Use `addOnFrameProcessCallback` to inspect each processed frame before a final
+result is available or to drive custom scan-step behavior from your own logic.
+The callback uses the exported `BlinkIdFrameProcessCallback` type:
+
+```typescript
+export type BlinkIdFrameProcessCallback = (
+  frameResult: BlinkIdProcessResult,
+  advanceToNextStep: () => Promise<void>,
+  triggerStepTimeout: () => void,
+  getLastFrame: () => ArrayBuffer,
+) => void;
+```
+
+Callback parameters:
+
+- `frameResult` - the `BlinkIdProcessResult` for the current frame. It contains
+  input image analysis and result completeness data for that frame, but it is not
+  the final `BlinkIdScanningResult`.
+- `advanceToNextStep` - manually advances the session to the next required scan
+  step. Use this when your custom frame-level logic decides that the active side
+  or barcode step is complete. This can also finish the scan when
+  `frameResult` already contains all data your integration needs, even if the
+  default flow would keep waiting for a barcode or another optional step that
+  the user cannot capture reliably.
+- `triggerStepTimeout` - immediately triggers the scan-step timeout path for the
+  active step. Use this when custom validation decides the current step should
+  fail or stop waiting for more frames.
+- `getLastFrame` - returns the raw `ArrayBuffer` for the frame that produced
+  `frameResult`, useful for QA overlays, diagnostics, or custom capture tooling.
+
+```typescript
+const removeOnFrameProcess = uxManager.addOnFrameProcessCallback(
+  (frameResult, advanceToNextStep, triggerStepTimeout, getLastFrame) => {
+    if (hasAllRequiredData(frameResult)) {
+      void advanceToNextStep();
+      return;
+    }
+
+    if (shouldStopStep(frameResult)) {
+      triggerStepTimeout();
+      return;
+    }
+
+    const lastFrame = getLastFrame();
+    console.debug("Last processed frame bytes:", lastFrame.byteLength);
+  },
+);
+
+// Later, to stop receiving updates:
+removeOnFrameProcess();
+```
+
+### Observing Progress
+
+Use `addOnProgressCallback` to receive live BlinkID progress snapshots from the
+manager's internal RAF loop, capped at 30 FPS. This is useful for QA overlays,
+debug tooling, or custom telemetry.
+
+```javascript
+const removeOnProgress = uxManager.addOnProgressCallback((progress) => {
+  console.log(progress.uiStateKey);
+  console.log(progress.inactivity.remainingMs);
+  console.log(progress.perSide.remainingMs);
+  console.log(progress.partiallySupportedBarcodeResolve.remainingMs);
+});
+
+// Later, to stop receiving updates:
+removeOnProgress();
+```
+
+Each progress payload includes:
+
+- `uiStateKey` - current stabilized UI state
+- `mappedUiStateKey` - latest raw candidate state before stabilization
+- `inactivity` - configured, remaining, and status data for the inactivity timer
+- `perSide` - configured, remaining, and status data for the scan-step timer
+- `partiallySupportedBarcodeResolve` - configured, remaining, and status data for the partially supported barcode resolve timer
+- `playbackState` - current camera playback state
+- `isTimingActiveScanStep` - whether BlinkID is currently timing an active scan step
+
 ### Inspecting UI State
 
 Two getters provide visibility into the current UI state:
@@ -153,16 +285,62 @@ The output files will be available in the `dist/` and `types/` directories.
 
 ### Internationalization
 
-You can customize UI strings when creating the feedback UI:
+You can customize UI strings when creating the feedback UI. The canonical key shape is defined by [`src/ui/locales/en.ts`](src/ui/locales/en.ts); `LocalizationStrings` in [`src/ui/LocalizationContext.tsx`](src/ui/LocalizationContext.tsx) follows that object.
+
+#### v8000 breaking change: nested localization keys
+
+Older releases used **flat** top-level keys (for example `scan_the_barcode`, `help_modal_title_1`). Current releases use a **nested** object. Overrides in `feedbackUiOptions.localizationStrings` (or the third argument to `createBlinkIdFeedbackUi`) must use the new paths; flat keys are no longer read. If you overrode flat keys in 7.x, use the **Flat key migration (pre-v8000 → current)** table in the v8000 package `CHANGELOG.md` (from the major release changeset) for the old-key to new-path mapping.
+
+Example override with nested keys:
 
 ```typescript
 createBlinkIdFeedbackUi(uxManager, cameraUi, {
-   localizationStrings: {
-      scan_the_barcode: "Please scan the barcode"
-   }
+  localizationStrings: {
+    feedback_messages: {
+      scan_the_barcode: "Please scan the barcode",
+    },
+    timeout_modal: {
+      title: "Scan did not finish",
+    },
+  },
 });
 ```
 
+#### Structure overview
+
+Top-level groups in `en.ts`:
+
+- `feedback_messages` — short live feedback strings (blur, glare, scan-this-side hints, success ARIA labels).
+- `help_button` — `aria_label`, `tooltip` for the help entry point.
+- `help_modal` — shared chrome (`aria`, `back_btn`, `next_btn`, `done_btn`, `done_btn_aria`) plus three **flow groups** (`full_document`, `document_with_barcode`, `barcode_only`). Each group has step objects `visibility`, `lighting`, `blur` with `title`, `title_desktop`, `details`, `details_desktop` as applicable, and `camera_lens` with desktop-only `title_desktop` / `details_desktop` where used.
+- `onboarding_modal` — shared `aria`, `btn` plus the same three groups (`full_document`, `document_with_barcode`, `barcode_only`) with `title`, `title_desktop`, `details`, `details_desktop`.
+- `error_modal` — `cancel_btn`, `retry_btn` for error flows that expose those actions.
+- `document_filtered_modal`, `document_not_recognized_modal` — `title` and `details` for document filtering / unsupported UI.
+- `timeout_modal` — `title` and `details` for scan timeout / failure messaging.
+- `sdk_aria` — ARIA label for the scanning screen region.
+
+#### Extraction mode and which help/onboarding group is used
+
+`BlinkIdExtractionMode` (see [`src/core/extractionMode.ts`](src/core/extractionMode.ts)) drives which subtree under `help_modal` and `onboarding_modal` is shown. The mapping matches [`helpModalContentByExtractionMode`](src/ui/dialogs/HelpModal.tsx) and [`onboardingModalContentByExtractionMode`](src/ui/dialogs/OnboardingGuideModal.tsx):
+
+| Extraction mode           | `help_modal` / `onboarding_modal` group |
+| ------------------------- | ---------------------------------------- |
+| `full-document`           | `full_document`                          |
+| `document-with-barcode` | `document_with_barcode`                    |
+| `barcode-only`            | `barcode_only`                                |
+
+Feedback strings that depend on extraction mode (for example front vs barcode side) are selected in code via [`src/ui/feedbackMessages.ts`](src/ui/feedbackMessages.ts); new keys include `scan_the_barcode_side` and `keep_still` (used for the desktop blur path as a shorter “keep still” hint).
+
+#### English copy changes (not just nesting)
+
+- Several `feedback_messages` strings now say “**a** document” instead of “**the** document” where the copy is generic.
+- New dedicated copy for **barcode-only** and **document + barcode** paths under `help_modal.barcode`, `help_modal.capture_barcode`, and matching `onboarding_modal` groups.
+- New feedback keys: `scan_the_barcode_side`, `keep_still`.
+
+#### Other locales
+
+Every file under [`src/ui/locales/`](src/ui/locales/) follows the same nested structure as `en.ts`. If you maintain a fork or partial override, diff your strings against `en.ts` to pick up new keys and renamed paths.
+
 #### Provided Translations
 
 <details>