@smileid/usesmileid 12.0.2 → 12.1.1

package/src/presentation/flow/flow_navigation_manager.ts

@@ -1,1166 +0,0 @@
-import type { ScreenSpec } from "./dsl/builder/screens_builder";
-import type { FlowConfigurationSnapshot } from "./dsl/use_smile_id_flow_builder";
-import type { JobSubmissionState } from "./job_submission_state";
-import type { JobRequest } from "../../data/model/job_request";
-import type { UseSmileIDRepository } from "../../data/repository/use_smile_id_repository";
-import type { ConsentInformation, UserDetails } from "../../core/models/params";
-import { JobType } from "../../core/models/job_type";
-import { CaptureType } from "../../core/models/ml_config";
-import {
-  defaultFrameAspectRatio,
-  type DocumentType,
-} from "../../core/models/document_type";
-import type { JobSubmissionResponse } from "../../data/model/job_submission_response";
-import {
-  MissingJobTypeException,
-  MissingRequiredFieldException,
-} from "../../core/exception/job_validation_exceptions";
-import {
-  UseSmileIDAnalyticsEventTypes,
-  UseSmileIDAnalyticsParamKeys,
-  UseSmileIDAnalyticsScreenNames,
-  type UseSmileIDAnalyticsEventType,
-} from "./analytics/use_smile_id_analytics_event";
-import type { MetadataEntry } from "../../metadata/use_smile_id_metadata";
-import {
-  UseSmileIDMetadataFactory,
-  type MetadataProvider,
-} from "../../metadata/use_smile_id_metadata_factory";
-import {
-  DOCUMENT_BACK_IMAGE_ORIGIN_KEY,
-  DOCUMENT_FRONT_IMAGE_ORIGIN_KEY,
-  type DocumentImageOrigin,
-} from "../../metadata/document_image_origin";
-import { configurationMetadataEntries } from "../../metadata/metadata_configuration_mappers";
-import {
-  CAPTURE_IMAGE_COLOR_DEPTH,
-  CAPTURE_IMAGE_PIXEL_CONFIG,
-} from "../../metadata/captured_image_properties";
-import type { CaptureTelemetry } from "../screen/use_smile_id_capture_screen";
-import type { SdkConfig } from "../../data/model/sdk_config";
-import { numSamplesOverride } from "../../data/model/sdk_config";
-import {
-  decodeSmileIDToken,
-  type DecodedToken,
-} from "../../data/util/use_smile_id_token_decoder";
-import {
-  isTokenConsentComplete,
-  bindsRequiredUserDetails,
-  type TokenPayload,
-} from "../../data/model/token_payload";
-import {
-  isUserDetailsPayloadEmpty,
-  userDetailsPayloadFrom,
-} from "../../data/model/user_details_payload";
-import type { UserDetailsPayload } from "../../data/model/user_details_payload";
-import {
-  DocumentSide,
-  EnhancedSmartSelfieConfig,
-} from "@smileid/usesmileid_bridge";
-import { ScanPerformanceProfile } from "@smileid/usesmileid_bridge";
-
-/**
- * Internal flow navigation manager — owns the screen cursor, captured
- * artifacts, navigation primitives, job submission lifecycle, and a
- * subscribe pattern for React re-renders.
- *
- * Custom (not Expo Router / React Navigation) because screens are
- * partner-configurable via the DSL, not file-based routes; forcing a
- * routing library would conflict with the partner's own app routing.
- */
-type Listener = () => void;
-
-export type CapturedArtifacts = {
-  readonly selfiePath?: string;
-  readonly livenessPaths: readonly string[];
-  readonly frontDocumentPath?: string;
-  readonly backDocumentPath?: string;
-  readonly consentInformation?: ConsentInformation;
-};
-
-export type FlowExitReason =
-  | { readonly kind: "completed"; readonly job: JobSubmissionResponse }
-  | { readonly kind: "cancelled" }
-  | { readonly kind: "failed"; readonly error: unknown };
-
-export type FlowExitHandler = (reason: FlowExitReason) => void;
-
-export type FlowNavigationManagerOptions = {
-  readonly configuration: FlowConfigurationSnapshot;
-  readonly onExit: FlowExitHandler;
-  /**
-   * Dispatches the assembled `JobRequest`. Optional so capture-only /
-   * UI-only harnesses (no `b.network(...)`) can still mount. When
-   * absent, `beginSubmissionIfNeeded()` goes straight to a descriptive
-   * `failure` rather than spinning forever.
-   */
-  readonly repository?: UseSmileIDRepository;
-  /**
-   * Per-flow metadata provider; each `JobRequest` carries a fresh
-   * `metadata` snapshot via `make()`. Optional — capture-only harnesses
-   * fall back to a default factory. Production passes the same provider
-   * the networking factory created so `session_id` stays stable across
-   * every submission in the flow.
-   */
-  readonly metadataProvider?: MetadataProvider;
-};
-
-const DEFAULT_CONSENT: ConsentInformation = Object.freeze({
-  granted: false,
-  grantedAt: "",
-  noticeLanguage: "",
-  noticePrivacyPolicyUrl: "",
-});
-
-export class FlowNavigationManager {
-  /**
-   * Navigation stack and source of truth — top is the active screen.
-   * Active screen + first/last predicates derive from this path (no
-   * parallel index). Mutated only via the navigate* methods.
-   */
-  private _navigationPath: ScreenSpec[] = [];
-  private _captured: CapturedArtifacts = { livenessPaths: [] };
-  /**
-   * Set once the partner skips the document back side via the flip
-   * interstitial. Routes `getNextScreen()` past the back capture's preview so
-   * submission proceeds with `backDocument` unset. Cleared when the front is
-   * retaken.
-   */
-  private _documentBackSkipped = false;
-  /**
-   * How each captured document side was produced (auto / manual / gallery).
-   * Emitted as `DocumentFront/BackImageOrigin` submission metadata; an entry is
-   * removed when its side is retaken.
-   */
-  private readonly _documentImageOrigins = new Map<
-    DocumentSide,
-    DocumentImageOrigin
-  >();
-  // Capture telemetry recorded at capture completion (selfie + per document side).
-  private _selfieCaptureTelemetry: CaptureTelemetry | undefined;
-  private readonly _documentCaptureTelemetry = new Map<
-    DocumentSide,
-    CaptureTelemetry
-  >();
-  // Identifier of the camera used for the most recent capture.
-  private _cameraName: string | undefined;
-  // Accelerometer telemetry from the most recent capture (device_positions / movement).
-  private _devicePositions: readonly string[] = [];
-  private _deviceMovementDetected: number | null = null;
-  private _jobSubmissionState: JobSubmissionState = { kind: "notAttempted" };
-  private readonly _listeners = new Set<Listener>();
-  private readonly _steps: readonly ScreenSpec[];
-  private readonly _configuration: FlowConfigurationSnapshot;
-  private readonly _repository: UseSmileIDRepository | undefined;
-  private readonly _metadataProvider: MetadataProvider;
-  private readonly _onExit: FlowExitHandler;
-  private _disposed = false;
-  private _submissionResponse: JobSubmissionResponse | undefined;
-
-  /**
-   * Decoded `sdk_config` JWT claim, resolved once at construction.
-   * `undefined` for offline mode / no token / no valid claim — SDK
-   * defaults apply throughout the flow in those cases.
-   */
-  readonly resolvedSdkConfig: SdkConfig | undefined;
-
-  /** Canonical `partner_id` decoded from the JWT (raw); resolved via the [partnerId] getter. */
-  private readonly _resolvedPartnerId: string | undefined;
-
-  /**
-   * Token-bound user-detail/consent bindings decoded from the JWT
-   * `payload` claim, resolved once at construction alongside
-   * `resolvedSdkConfig`. `undefined` for offline mode / no token /
-   * legacy token — assembly then requires and sends everything exactly
-   * as before token support existed.
-   */
-  private readonly _resolvedTokenPayload: TokenPayload | undefined;
-
-  /**
-   * Partner identifier the capture screen stamps into the Smile EXIF tag — the tag's HMAC/AES
-   * keys derive from it and the backend validates the tag against the request's partner_id.
-   *
-   * Sourced from the JWT `partner_id` claim (server-canonical form, e.g. `"002"`) so the stamped
-   * value matches what the backend keys on; falls back to the partner-supplied config value when
-   * the claim is absent/blank. Empty = skip tagging.
-   */
-  get partnerId(): string {
-    const jwtPartnerId = this._resolvedPartnerId;
-    if (jwtPartnerId && jwtPartnerId.length > 0) return jwtPartnerId;
-    return this._configuration.network?.config?.partnerConfig?.partnerId ?? "";
-  }
-
-  /** Stable per-flow session id, stamped into every analytics event's `session_id`. */
-  private readonly _sessionId: string;
-
-  /** Submission attempts so far — stamped into `job_submitted` as `attempt`. */
-  private _submissionAttemptCount = 0;
-
-  constructor(options: FlowNavigationManagerOptions) {
-    this._configuration = options.configuration;
-    this._onExit = options.onExit;
-    this._repository = options.repository;
-    // Fall back to a fresh factory so capture-only harnesses still build
-    // well-formed requests; the factory reads expo-device lazily and
-    // degrades to empty values when the peer dep is absent.
-    this._metadataProvider =
-      options.metadataProvider ?? new UseSmileIDMetadataFactory();
-    this._sessionId = this._metadataProvider.sessionId;
-    const decodedToken = FlowNavigationManager._decodeToken(
-      options.configuration,
-    );
-    this.resolvedSdkConfig = decodedToken?.sdkConfig;
-    this._resolvedPartnerId = decodedToken?.partnerId;
-    this._resolvedTokenPayload = decodedToken?.tokenPayload;
-    // Token consent always wins: a complete binding drops the consent
-    // screen from the flow — the server injects the token's record, so
-    // nothing is collected here.
-    const steps = options.configuration.screens.steps;
-    this._steps = isTokenConsentComplete(decodedToken?.tokenPayload?.consent)
-      ? steps.filter((s) => s.kind !== "consent")
-      : steps;
-    // Seed the path with the first screen so currentScreen/renderer have a
-    // deterministic start. Empty path → host renders the "no screens"
-    // sentinel (validation rejects empty screens at build time anyway).
-    const firstScreen = this._steps[0];
-    if (firstScreen) {
-      this._navigationPath = [firstScreen];
-    }
-    this._logEvent(UseSmileIDAnalyticsEventTypes.flowStarted, {
-      [UseSmileIDAnalyticsParamKeys.jobType]: this._jobTypeName(),
-    });
-    if (firstScreen) {
-      this._logEvent(UseSmileIDAnalyticsEventTypes.screenViewed, {
-        [UseSmileIDAnalyticsParamKeys.screenName]:
-          this._screenAnalyticsName(firstScreen),
-      });
-    }
-  }
-
-  get configuration(): FlowConfigurationSnapshot {
-    return this._configuration;
-  }
-
-  /** Whether any selfie step enabled Enhanced Smart Selfie (drives the instructions hero swap and oval-progress suppression). */
-  get enhancedLivenessEnabled(): boolean {
-    return this._steps.some(
-      (step) =>
-        step.kind === "capture" &&
-        step.config.selfieConfig?.enableEnhancedLiveness === true,
-    );
-  }
-
-  /** Document type from the flow's document capture step, if any (drives the instructions document variant). */
-  get documentType(): DocumentType | undefined {
-    for (const step of this._steps) {
-      if (
-        step.kind === "capture" &&
-        step.config.captureType === CaptureType.document
-      ) {
-        return step.config.documentConfig?.documentType;
-      }
-    }
-    return undefined;
-  }
-
-  /**
-   * Resolved document capture-frame aspect ratio (width / height), shared by
-   * capture, preview, and processing. Precedence: type `knownAspectRatio` →
-   * partner `knownIdAspectRatio` → orientation default.
-   */
-  get documentFrameAspectRatio(): number | undefined {
-    for (const step of this._steps) {
-      if (
-        step.kind === "capture" &&
-        step.config.captureType === CaptureType.document
-      ) {
-        const documentConfig = step.config.documentConfig;
-        return (
-          documentConfig?.resolvedAspectRatio ??
-          defaultFrameAspectRatio(
-            documentConfig?.documentType?.orientation ?? "Landscape",
-          )
-        );
-      }
-    }
-    return undefined;
-  }
-
-  // --- navigation path --------------------------------------------------
-
-  /** Read-only navigation stack; top is the active screen. */
-  get navigationPath(): readonly ScreenSpec[] {
-    return this._navigationPath;
-  }
-
-  /** Active screen (top of the path); `undefined` only when no screens are configured. */
-  get currentScreen(): ScreenSpec | undefined {
-    return this._navigationPath[this._navigationPath.length - 1];
-  }
-
-  /**
-   * Depth of the active screen — stable id for React view identity so
-   * stack frames at the same configured-screen position stay distinct.
-   */
-  get currentDepth(): number {
-    return this._navigationPath.length - 1;
-  }
-
-  get isFirstScreen(): boolean {
-    return this._navigationPath.length <= 1;
-  }
-
-  get isLastScreen(): boolean {
-    return this.getNextScreen() === undefined;
-  }
-
-  /** Next screen `navigateToNext()` would land on; `undefined` at the terminal screen. */
-  getNextScreen(): ScreenSpec | undefined {
-    const current = this.currentScreen;
-    if (!current) return undefined;
-    const currentIdx = this._steps.indexOf(current);
-    if (currentIdx < 0) return undefined;
-
-    // Per-side document loop: after previewing the FRONT, route back to the
-    // document capture step to capture the BACK. Gated so it fires only on a
-    // document preview with the back still pending and not skipped — the back
-    // preview (back already captured) falls through to the linear next step.
-    if (
-      current.kind === "preview" &&
-      this._precedingStepIsDocumentCapture(currentIdx) &&
-      this.documentCapturesBack() &&
-      this._captured.backDocumentPath === undefined &&
-      !this._documentBackSkipped
-    ) {
-      const documentCapture = this._steps[currentIdx - 1];
-      if (documentCapture !== undefined) return documentCapture;
-    }
-
-    // Back skipped at the interstitial: skip the document preview that would
-    // otherwise follow the capture and advance past it (no back to preview).
-    if (
-      current.kind === "capture" &&
-      current.config.captureType === CaptureType.document &&
-      this._documentBackSkipped
-    ) {
-      const next = this._steps[currentIdx + 1];
-      if (next?.kind === "preview") return this._steps[currentIdx + 2];
-    }
-
-    // At the document capture step with the front captured, the back still
-    // pending, and no document preview to drive the per-side loop, re-enter the
-    // capture step for the back side so captureBothSides is honoured even when
-    // the flow omits the document preview { } step. When a preview does follow,
-    // the per-side loop above handles the back instead.
-    if (
-      current.kind === "capture" &&
-      current.config.captureType === CaptureType.document &&
-      this.documentCapturesBack() &&
-      this._captured.frontDocumentPath !== undefined &&
-      this._captured.backDocumentPath === undefined &&
-      !this._documentBackSkipped &&
-      !this.documentPreviewFollowsCapture()
-    ) {
-      return current;
-    }
-
-    return this._steps[currentIdx + 1];
-  }
-
-  /**
-   * Advance to the next screen. Past the last screen, exits via `onExit`
-   * `{ kind: 'completed', job }` (job is the successful response, or an
-   * empty-fields stand-in for flows with no processing screen).
-   *
-   * Advancing into a `processing` screen sets `loading` synchronously
-   * before the async submit, closing the race with the screen's
-   * mount-time `beginSubmissionIfNeeded()` so it never flashes
-   * `notAttempted`.
-   */
-  navigateToNext(): void {
-    if (this._disposed) return;
-    const nextScreen = this.getNextScreen();
-    if (!nextScreen) {
-      // Past the last screen: deliver the stored success response,
-      // surface a failure, else the empty-fields completed carrier
-      // (flows with no processing screen still get `completed`).
-      const state = this._jobSubmissionState;
-      if (this._submissionResponse) {
-        this._finishFlow({ kind: "completed", job: this._submissionResponse });
-        return;
-      }
-      if (state.kind === "failure") {
-        this._finishFlow({ kind: "failed", error: state.error });
-        return;
-      }
-      const job: JobSubmissionResponse =
-        state.kind === "success"
-          ? state.response
-          : { userId: "", jobId: "", status: "", message: "" };
-      this._finishFlow({ kind: "completed", job });
-      return;
-    }
-    this._navigationPath = [...this._navigationPath, nextScreen];
-    this._logEvent(UseSmileIDAnalyticsEventTypes.screenViewed, {
-      [UseSmileIDAnalyticsParamKeys.screenName]:
-        this._screenAnalyticsName(nextScreen),
-    });
-    // Mark loading synchronously so the processing screen's mount-time
-    // beginSubmissionIfNeeded() sees the transition has started — guards
-    // the brief notAttempted flash before the async submit is scheduled.
-    if (
-      nextScreen.kind === "processing" &&
-      this._jobSubmissionState.kind === "notAttempted" &&
-      this._repository !== undefined
-    ) {
-      this._jobSubmissionState = { kind: "loading" };
-    }
-    this._notify();
-    if (
-      nextScreen.kind === "processing" &&
-      this._jobSubmissionState.kind === "loading" &&
-      this._repository !== undefined
-    ) {
-      // Macrotask defer so React paints the loading processing screen
-      // before _submit blocks the JS thread with request assembly +
-      // signing. The pre-set loading keeps beginSubmissionIfNeeded() a
-      // no-op, so it still submits exactly once.
-      setTimeout(() => {
-        if (this._disposed) return;
-        void this._submit();
-      }, 0);
-    }
-  }
-
-  /** Pop the active screen; from the first screen, exits via `onExit` `{ kind: 'cancelled' }`. */
-  navigateBack(): void {
-    if (this._disposed) return;
-    if (this.isFirstScreen) {
-      this._onExit({ kind: "cancelled" });
-      return;
-    }
-    // Going back from a non-first screen is a retake of the prior step.
-    this._logEvent(UseSmileIDAnalyticsEventTypes.retakeRequested);
-    this._navigationPath = this._navigationPath.slice(0, -1);
-    this._notify();
-  }
-
-  /** Reset the path to the first screen (flow restart after terminal failure, manager kept alive). */
-  navigateToStart(): void {
-    if (this._disposed) return;
-    const firstScreen = this._steps[0];
-    this._navigationPath = firstScreen ? [firstScreen] : [];
-    this._notify();
-  }
-
-  /** Exit the flow with a partner-supplied reason (processing onExit, consent denied, etc.). */
-  exit(reason: FlowExitReason = { kind: "cancelled" }): void {
-    if (this._disposed) return;
-    this._finishFlow(reason);
-  }
-
-  // --- captured artifacts -----------------------------------------------
-
-  get captured(): CapturedArtifacts {
-    return this._captured;
-  }
-
-  setCapturedSelfie(
-    selfiePath: string,
-    livenessPaths: readonly string[],
-  ): void {
-    if (this._disposed) return;
-    this._captured = {
-      ...this._captured,
-      selfiePath,
-      livenessPaths: Object.freeze([...livenessPaths]),
-    };
-    this._logEvent(UseSmileIDAnalyticsEventTypes.selfieCaptured, {
-      [UseSmileIDAnalyticsParamKeys.livenessImageCount]: String(
-        livenessPaths.length,
-      ),
-    });
-    this._notify();
-  }
-
-  setCapturedFrontDocument(path: string): void {
-    if (this._disposed) return;
-    this._captured = { ...this._captured, frontDocumentPath: path };
-    this._logEvent(UseSmileIDAnalyticsEventTypes.documentCaptured, {
-      [UseSmileIDAnalyticsParamKeys.documentSide]: "front",
-    });
-    this._notify();
-  }
-
-  setCapturedBackDocument(path: string): void {
-    if (this._disposed) return;
-    this._captured = { ...this._captured, backDocumentPath: path };
-    // `both` is the single completion-event value for a two-sided capture.
-    this._logEvent(UseSmileIDAnalyticsEventTypes.documentCaptured, {
-      [UseSmileIDAnalyticsParamKeys.documentSide]: "both",
-    });
-    this._notify();
-  }
-
-  // --- document per-side preview loop -----------------------------------
-
-  /** Whether the configured document capture asks for a back side. */
-  documentCapturesBack(): boolean {
-    for (const step of this._steps) {
-      if (
-        step.kind === "capture" &&
-        step.config.captureType === CaptureType.document
-      ) {
-        const documentConfig = step.config.documentConfig;
-        return (
-          documentConfig?.documentType?.hasBackSide === true &&
-          (documentConfig?.captureBothSides ?? false)
-        );
-      }
-    }
-    return false;
-  }
-
-  /** Whether a `preview {}` immediately follows the document capture step. */
-  documentPreviewFollowsCapture(): boolean {
-    const index = this._steps.findIndex(
-      (step) =>
-        step.kind === "capture" &&
-        step.config.captureType === CaptureType.document,
-    );
-    if (index < 0) return false;
-    return this._steps[index + 1]?.kind === "preview";
-  }
-
-  /** Whether the active preview previews a document side (vs the selfie). */
-  currentPreviewIsDocument(): boolean {
-    const current = this.currentScreen;
-    if (!current || current.kind !== "preview") return false;
-    return this._precedingStepIsDocumentCapture(this._steps.indexOf(current));
-  }
-
-  /** Path of the document side under review: the back if captured, else the front. */
-  currentDocumentPreviewPath(): string | undefined {
-    return this._captured.backDocumentPath ?? this._captured.frontDocumentPath;
-  }
-
-  /**
-   * Discard the side under review for re-capture: the back if captured,
-   * else the front (which also un-skips the back). Does not navigate.
-   */
-  retakeCurrentDocumentSide(): void {
-    if (this._disposed) return;
-    const next: {
-      -readonly [K in keyof CapturedArtifacts]: CapturedArtifacts[K];
-    } = { ...this._captured };
-    if (next.backDocumentPath !== undefined) {
-      delete next.backDocumentPath;
-      this._documentImageOrigins.delete(DocumentSide.Back);
-    } else {
-      delete next.frontDocumentPath;
-      this._documentImageOrigins.delete(DocumentSide.Front);
-      this._documentBackSkipped = false;
-    }
-    this._captured = next;
-    this._notify();
-  }
-
-  /** Skip the document back side from the flip interstitial ("Skip"). */
-  skipDocumentBack(): void {
-    if (this._disposed) return;
-    this._documentBackSkipped = true;
-    this._notify();
-  }
-
-  /**
-   * Record how a side was produced (→ `DocumentFront/BackImageOrigin`
-   * metadata). Metadata-only, so it intentionally does not `_notify()`.
-   */
-  recordDocumentImageOrigin(
-    side: DocumentSide,
-    origin: DocumentImageOrigin,
-  ): void {
-    if (this._disposed) return;
-    this._documentImageOrigins.set(side, origin);
-  }
-
-  /** Records selfie capture telemetry (duration + retries) at capture completion. */
-  recordSelfieCaptureTelemetry(telemetry: CaptureTelemetry): void {
-    if (this._disposed) return;
-    this._selfieCaptureTelemetry = telemetry;
-    this._captureCameraName(telemetry);
-  }
-
-  /** Records per-side document capture telemetry at each side's completion. */
-  recordDocumentCaptureTelemetry(
-    side: DocumentSide,
-    telemetry: CaptureTelemetry,
-  ): void {
-    if (this._disposed) return;
-    this._documentCaptureTelemetry.set(side, telemetry);
-    this._captureCameraName(telemetry);
-  }
-
-  private _captureCameraName(telemetry: CaptureTelemetry): void {
-    if (telemetry.cameraName) this._cameraName = telemetry.cameraName;
-    if (telemetry.devicePositions.length > 0) {
-      this._devicePositions = telemetry.devicePositions;
-      this._deviceMovementDetected = telemetry.deviceMovementDetected;
-    }
-  }
-
-  /** Per-side document origin wire entries (front then back; omitted when unset). */
-  private _documentImageOriginEntries(): MetadataEntry[] {
-    const entries: MetadataEntry[] = [];
-    const front = this._documentImageOrigins.get(DocumentSide.Front);
-    if (front !== undefined) {
-      entries.push({ name: DOCUMENT_FRONT_IMAGE_ORIGIN_KEY, value: front });
-    }
-    const back = this._documentImageOrigins.get(DocumentSide.Back);
-    if (back !== undefined) {
-      entries.push({ name: DOCUMENT_BACK_IMAGE_ORIGIN_KEY, value: back });
-    }
-    return entries;
-  }
-
-  /**
-   * Capture telemetry + image-property wire entries. Durations and retries keep
-   * a meaningful 0 (capture ran) and are omitted only when that capture type
-   * never ran. Color depth / pixel config are emitted for each present capture;
-   * document sizes when measured.
-   */
-  private _captureTelemetryEntries(): MetadataEntry[] {
-    const entries: MetadataEntry[] = [];
-    const push = (name: string, value: string) => entries.push({ name, value });
-
-    const selfie = this._selfieCaptureTelemetry;
-    if (selfie) {
-      // Duration + retries keep a meaningful 0 (capture ran); telemetry is absent only when the
-      // capture type never ran.
-      push("selfie_capture_duration_ms", String(selfie.durationMs));
-      push("selfie_capture_retries", String(selfie.retries));
-    }
-    if (this._captured.selfiePath !== undefined) {
-      push("selfie_image_color_depth", String(CAPTURE_IMAGE_COLOR_DEPTH));
-      push("selfie_image_pixel_config", CAPTURE_IMAGE_PIXEL_CONFIG);
-    }
-    if (this._cameraName) {
-      push("camera_name", this._cameraName);
-    }
-    if (this._devicePositions.length > 0) {
-      push("device_positions", JSON.stringify(this._devicePositions));
-      if (this._deviceMovementDetected !== null) {
-        push("device_movement_detected", String(this._deviceMovementDetected));
-      }
-    }
-
-    const sideKey = (side: DocumentSide) =>
-      side === DocumentSide.Back ? "back" : "front";
-    for (const side of [DocumentSide.Front, DocumentSide.Back]) {
-      const key = sideKey(side);
-      const telemetry = this._documentCaptureTelemetry.get(side);
-      if (telemetry) {
-        push(
-          `document_${key}_capture_duration_ms`,
-          String(telemetry.durationMs),
-        );
-        push(`document_${key}_capture_retries`, String(telemetry.retries));
-        push(
-          `document_${key}_image_color_depth`,
-          String(CAPTURE_IMAGE_COLOR_DEPTH),
-        );
-        push(`document_${key}_image_pixel_config`, CAPTURE_IMAGE_PIXEL_CONFIG);
-      }
-    }
-    // Per-image original + final compressed sizes are stamped in the repository around the
-    // compression pass (it owns both the before and after byte counts), not here.
-    return entries;
-  }
-
-  private _precedingStepIsDocumentCapture(index: number): boolean {
-    const preceding = this._steps[index - 1];
-    return (
-      preceding?.kind === "capture" &&
-      preceding.config.captureType === CaptureType.document
-    );
-  }
-
-  setConsent(info: ConsentInformation): void {
-    if (this._disposed) return;
-    this._captured = { ...this._captured, consentInformation: info };
-    this._logEvent(UseSmileIDAnalyticsEventTypes.consentCaptured, {
-      [UseSmileIDAnalyticsParamKeys.decision]: "granted",
-    });
-    this._notify();
-  }
-
-  // --- job submission ---------------------------------------------------
-
-  get jobSubmissionState(): JobSubmissionState {
-    return this._jobSubmissionState;
-  }
-
-  /**
-   * Idempotent submission entry point (called on processing-screen
-   * mount). The `notAttempted` guard prevents re-mounts re-firing.
-   */
-  beginSubmissionIfNeeded(): void {
-    if (this._disposed) return;
-    if (this._jobSubmissionState.kind !== "notAttempted") return;
-    void this._submit();
-  }
-
-  /**
-   * Reset to `notAttempted` and re-fire submission (processing screen's
-   * onRetry). Ignored while a submission is in flight — resetting then would
-   * defeat `beginSubmissionIfNeeded()`'s single-flight guard.
-   */
-  retrySubmission(): void {
-    if (this._disposed) return;
-    if (this._jobSubmissionState.kind === "loading") return;
-    this._setSubmissionState({ kind: "notAttempted" });
-    this.beginSubmissionIfNeeded();
-  }
-
-  private _setSubmissionState(state: JobSubmissionState): void {
-    if (this._disposed) return;
-    this._jobSubmissionState = state;
-    this._notify();
-  }
-
-  /**
-   * Build the request, dispatch via repository, update state. Errors
-   * from `_assembleJob` (missing captures / bad job type) map to the
-   * `failure` state rather than propagating as unhandled rejections.
-   */
-  private async _submit(): Promise<void> {
-    if (!this._repository) {
-      this._setSubmissionState({
-        kind: "failure",
-        error: new Error(
-          "Job submission not configured — no network/repository was " +
-            "supplied to <UseSmileIDBuilder>. Call `b.network((n) => n.config((c) => " +
-            "{ c.token = ...; c.partnerConfig((p) => { p.partnerId = ...; }); }))`.",
-        ),
-      });
-      return;
-    }
-
-    let request: JobRequest;
-    try {
-      request = this._assembleJob();
-    } catch (error) {
-      this._setSubmissionState({
-        kind: "failure",
-        error: error instanceof Error ? error : new Error(String(error)),
-      });
-      return;
-    }
-
-    this._setSubmissionState({ kind: "loading" });
-    this._submissionAttemptCount += 1;
-    this._logEvent(UseSmileIDAnalyticsEventTypes.jobSubmitted, {
-      [UseSmileIDAnalyticsParamKeys.jobType]: this._jobTypeName(),
-      [UseSmileIDAnalyticsParamKeys.attempt]: String(
-        this._submissionAttemptCount,
-      ),
-    });
-    const result = await this._repository.submit(request);
-    if (this._disposed) return;
-    if (result.status === "success") {
-      // Cache so a later navigateToNext() past the last screen can
-      // deliver the result without rebuilding the request (capture
-      // artifacts may have been released by then).
-      this._submissionResponse = result.value;
-      this._setSubmissionState({ kind: "success", response: result.value });
-    } else if (result.status === "failure") {
-      // `result.error` is `unknown`; coerce defensively in case a
-      // mock/partner repository hands back a non-Error.
-      const error =
-        result.error instanceof Error
-          ? result.error
-          : new Error(String(result.error));
-      this._setSubmissionState({ kind: "failure", error });
-    }
-    // No `cancelled` branch: that outcome comes only from a user-initiated exit.
-  }
-
-  /**
-   * Build a typed `JobRequest` from `jobType` + captured artifacts.
-   * Throws a descriptive message when a required capture is missing.
-   */
-  private _assembleJob(): JobRequest {
-    const config = this._configuration;
-    const jobType = config.network?.config?.jobType ?? JobType.unknown;
-    // Token consent always wins: the `consent` part is omitted — the
-    // server injects the token's record — and any local preset or
-    // capture is ignored. Without a token binding, a local source
-    // (captured on the consent screen, else the builder preset) is
-    // sent in full, and the legacy DEFAULT_CONSENT placeholder covers
-    // the no-source case.
-    const consent = isTokenConsentComplete(this._resolvedTokenPayload?.consent)
-      ? undefined
-      : (this._captured.consentInformation ??
-        config.consentInformation ??
-        DEFAULT_CONSENT);
-    const consentField = consent !== undefined ? { consent } : {};
-    // Build the per-submission metadata snapshot so it travels on the
-    // request (API layer serializes `request.metadata` directly).
-    // Dynamic fields (orientation, locale, timezone) re-resolve per
-    // make() so a mid-flow rotation is captured. resolvedSdkConfig drives
-    // sdk_config_source + image_width/height provenance.
-    const baseMetadata = this._metadataProvider.make(this.resolvedSdkConfig);
-    // Append the per-side document origins plus the partner's builder setup and
-    // the active detection models, all as flat wire entries.
-    // configurationMetadataEntries always contributes the builder + model config objects, so
-    // there is always at least one extra entry to append.
-    const extraEntries = [
-      ...this._documentImageOriginEntries(),
-      ...this._captureTelemetryEntries(),
-      ...configurationMetadataEntries(config),
-    ];
-    const metadata = baseMetadata.withAdditionalEntries(extraEntries);
-
-    switch (jobType) {
-      // enableEnhancedLiveness is a screen-level capture flag, not a
-      // distinct job type — enrollment still hits /v3/registration.
-      case JobType.smartSelfieEnrollment: {
-        const selfie = this._requireSelfie();
-        const userDetails = this._requireUserDetails(config);
-        return {
-          jobType: JobType.smartSelfieEnrollment,
-          selfieImage: selfie.selfiePath,
-          livenessImages: selfie.livenessPaths,
-          ...(userDetails !== undefined ? { userDetails } : {}),
-          ...consentField,
-          metadata,
-          enhanced: false,
-          expectedLivenessImageCount: this._expectedLivenessImageCount(),
-        };
-      }
-
-      case JobType.smartSelfieAuthentication: {
-        const selfie = this._requireSelfie();
-        const userDetails = this._requireUserDetails(config);
-        const userId = this._requireUserId(config);
-        return {
-          jobType: JobType.smartSelfieAuthentication,
-          selfieImage: selfie.selfiePath,
-          livenessImages: selfie.livenessPaths,
-          ...(userDetails !== undefined ? { userDetails } : {}),
-          userId,
-          ...consentField,
-          metadata,
-          enhanced: false,
-          expectedLivenessImageCount: this._expectedLivenessImageCount(),
-        };
-      }
-
-      case JobType.biometricKyc: {
-        const selfie = this._requireSelfie();
-        const params = config.biometricKYCParams;
-        if (!params) {
-          throw new MissingRequiredFieldException({
-            fieldName: "biometricKYCParams",
-          });
-        }
-        const userDetails = this._requireUserDetails(config);
-        return {
-          jobType: JobType.biometricKyc,
-          selfieImage: selfie.selfiePath,
-          livenessImages: selfie.livenessPaths,
-          params,
-          ...(userDetails !== undefined ? { userDetails } : {}),
-          ...consentField,
-          metadata,
-          expectedLivenessImageCount: this._expectedLivenessImageCount(),
-        };
-      }
-
-      case JobType.documentVerification: {
-        const selfie = this._requireSelfie();
-        const front = this._requireFrontDocument();
-        const params = config.documentVerificationParams;
-        if (!params) {
-          throw new MissingRequiredFieldException({
-            fieldName: "documentVerificationParams",
-          });
-        }
-        const userDetails = this._requireUserDetails(config);
-        return {
-          jobType: JobType.documentVerification,
-          ...this._documentRequestFields(selfie, front),
-          country: params.country,
-          // Optional — omit when unset so the server classifies the document.
-          ...(params.idType ? { idType: params.idType } : {}),
-          ...(userDetails !== undefined ? { userDetails } : {}),
-          ...consentField,
-          metadata,
-          expectedLivenessImageCount: this._expectedLivenessImageCount(),
-        };
-      }
-
-      case JobType.enhancedDocumentVerification: {
-        const selfie = this._requireSelfie();
-        const front = this._requireFrontDocument();
-        const params = config.enhancedDocumentVerificationParams;
-        if (!params) {
-          throw new MissingRequiredFieldException({
-            fieldName: "enhancedDocumentVerificationParams",
-          });
-        }
-        const userDetails = this._requireUserDetails(config);
-        return {
-          jobType: JobType.enhancedDocumentVerification,
-          ...this._documentRequestFields(selfie, front),
-          country: params.country,
-          idType: params.idType,
-          ...(userDetails !== undefined ? { userDetails } : {}),
-          ...consentField,
-          metadata,
-          expectedLivenessImageCount: this._expectedLivenessImageCount(),
-        };
-      }
-
-      case JobType.enhancedKyc: {
-        const params = config.enhancedKYCParams;
-        if (!params) {
-          throw new MissingRequiredFieldException({
-            fieldName: "enhancedKYCParams",
-          });
-        }
-        const userDetails = this._requireUserDetails(config);
-        return {
-          jobType: JobType.enhancedKyc,
-          params,
-          ...(userDetails !== undefined ? { userDetails } : {}),
-          ...consentField,
-          metadata,
-        };
-      }
-
-      case JobType.bvn: {
-        // Dedicated `bvn` request kind; the repository rejects it with
-        // "BVN submission is not yet supported" until the endpoint lands.
-        // Deliberately not silently mapped onto /v3/enhanced_kyc so
-        // partners see the unsupported state explicitly.
-        const params = config.enhancedKYCParams;
-        if (!params) {
-          throw new MissingRequiredFieldException({
-            fieldName: "enhancedKYCParams",
-          });
-        }
-        const userDetails = this._requireUserDetails(config);
-        return {
-          jobType: JobType.bvn,
-          params,
-          ...(userDetails !== undefined ? { userDetails } : {}),
-          ...consentField,
-          metadata,
-        };
-      }
-
-      case JobType.unknown:
-      default:
-        throw new MissingJobTypeException();
-    }
-  }
-
-  private _requireSelfie(): {
-    readonly selfiePath: string;
-    readonly livenessPaths: readonly string[];
-  } {
-    const { selfiePath, livenessPaths } = this._captured;
-    if (!selfiePath) {
-      throw new MissingRequiredFieldException({ fieldName: "selfieImage" });
-    }
-    return { selfiePath, livenessPaths };
-  }
-
-  /**
-   * Resolve `b.userDetails` for the wire. May legitimately return
-   * `undefined` when the token binds every required field
-   * (`given_names`, `last_name`, and a contact field) — the
-   * `user_details` part is then omitted and the server injects the
-   * token's values. Otherwise throws exactly as before token support.
-   */
-  private _requireUserDetails(
-    config: FlowConfigurationSnapshot,
-  ): UserDetailsPayload | undefined {
-    const userDetails = config.userDetails;
-    if (!userDetails) {
-      if (bindsRequiredUserDetails(this._resolvedTokenPayload)) {
-        return undefined;
-      }
-      throw new MissingRequiredFieldException({ fieldName: "userDetails" });
-    }
-    const payload = userDetailsPayloadFrom(
-      userDetails,
-      this._resolvedTokenPayload,
-    );
-    return isUserDetailsPayloadEmpty(payload) ? undefined : payload;
-  }
-
-  /**
-   * Resolve `b.userId` for smartSelfieAuthentication —
-   * `/v3/authentication` requires the prior-enrollment `user_id` to
-   * match the attempt. Throws `MissingRequiredFieldException` if blank.
-   */
-  private _requireUserId(config: FlowConfigurationSnapshot): string {
-    const userId = config.userId?.trim();
-    if (!userId) {
-      throw new MissingRequiredFieldException({ fieldName: "userId" });
-    }
-    return userId;
-  }
-
-  private _requireFrontDocument(): string {
-    const { frontDocumentPath } = this._captured;
-    if (!frontDocumentPath) {
-      throw new MissingRequiredFieldException({ fieldName: "frontDocument" });
-    }
-    return frontDocumentPath;
-  }
-
-  /** Capture-artifact fields shared by both document request variants. */
-  private _documentRequestFields(
-    selfie: {
-      readonly selfiePath: string;
-      readonly livenessPaths: readonly string[];
-    },
-    frontDocument: string,
-  ): {
-    readonly selfieImage: string;
-    readonly livenessImages: readonly string[];
-    readonly frontDocument: string;
-    readonly backDocument?: string;
-  } {
-    const { backDocumentPath } = this._captured;
-    return {
-      selfieImage: selfie.selfiePath,
-      livenessImages: selfie.livenessPaths,
-      frontDocument,
-      ...(backDocumentPath ? { backDocument: backDocumentPath } : {}),
-    };
-  }
-
-  // --- analytics --------------------------------------------------------
-
-  /** Emit terminal `flow_completed` (completed/failed only; not cancelled), then exit via `onExit`. */
-  private _finishFlow(reason: FlowExitReason): void {
-    if (reason.kind === "completed") {
-      const extras: Record<string, string> = {
-        [UseSmileIDAnalyticsParamKeys.result]: "success",
-      };
-      if (reason.job.jobId) {
-        extras[UseSmileIDAnalyticsParamKeys.jobId] = reason.job.jobId;
-      }
-      this._logEvent(UseSmileIDAnalyticsEventTypes.flowCompleted, extras);
-    } else if (reason.kind === "failed") {
-      this._logEvent(UseSmileIDAnalyticsEventTypes.flowCompleted, {
-        [UseSmileIDAnalyticsParamKeys.result]: "failure",
-        [UseSmileIDAnalyticsParamKeys.errorMessage]:
-          reason.error instanceof Error
-            ? reason.error.message
-            : String(reason.error),
-      });
-    }
-    this._onExit(reason);
-  }
-
-  /** Forward a lifecycle event to `onAnalyticsEvent`, adding `session_id` + `timestamp`. No-op without a callback. */
-  private _logEvent(
-    type: UseSmileIDAnalyticsEventType,
-    extras: Readonly<Record<string, string>> = {},
-  ): void {
-    const onAnalyticsEvent = this._configuration.onAnalyticsEvent;
-    if (!onAnalyticsEvent) return;
-    onAnalyticsEvent({
-      type,
-      extras: {
-        ...extras,
-        [UseSmileIDAnalyticsParamKeys.sessionId]: this._sessionId,
-        [UseSmileIDAnalyticsParamKeys.timestamp]: String(Date.now()),
-      },
-    });
-  }
-
-  private _jobTypeName(): string {
-    return String(
-      this._configuration.network?.config?.jobType ?? JobType.unknown,
-    );
-  }
-
-  private _screenAnalyticsName(screen: ScreenSpec): string {
-    const names: Record<ScreenSpec["kind"], string> = {
-      consent: UseSmileIDAnalyticsScreenNames.consent,
-      instructions: UseSmileIDAnalyticsScreenNames.instructions,
-      capture: UseSmileIDAnalyticsScreenNames.capture,
-      preview: UseSmileIDAnalyticsScreenNames.preview,
-      processing: UseSmileIDAnalyticsScreenNames.processing,
-    };
-    return names[screen.kind];
-  }
-
-  // --- subscription -----------------------------------------------------
-
-  /** Subscribe to state changes; returns an unsubscribe (safe after `dispose()`). */
-  subscribe(listener: Listener): () => void {
-    this._listeners.add(listener);
-    return () => {
-      this._listeners.delete(listener);
-    };
-  }
-
-  /** Tear down — drop listeners, make methods no-ops (orchestrator's useEffect cleanup). */
-  dispose(): void {
-    this._disposed = true;
-    this._listeners.clear();
-  }
-
-  /**
-   * Expected liveness image count: ESS uses its fixed count (head-turn
-   * flow self-manages); else the token's livenessImageCount override;
-   * else the ScanPerformanceProfile default (`numSamples - 1`).
-   */
-  private _expectedLivenessImageCount(): number {
-    const isEnhancedLiveness = this.enhancedLivenessEnabled;
-    if (isEnhancedLiveness) {
-      return EnhancedSmartSelfieConfig.EXPECTED_LIVENESS_IMAGE_COUNT;
-    }
-    const override = numSamplesOverride(this.resolvedSdkConfig);
-    if (override !== undefined) {
-      // numSamplesOverride = livenessImageCount + 1; subtract the selfie.
-      return override - 1;
-    }
-    // Profile numSamples (default Balanced = 8) minus the reference selfie.
-    const profileNumSamples =
-      this._configuration.ml?.analyzers.selfieConfig?.numSamples ??
-      ScanPerformanceProfile.Balanced.numSamples;
-    return profileNumSamples - 1;
-  }
-
-  /**
-   * Decode the partner JWT into its claims (`sdk_config`, `partner_id`). `undefined` for offline
-   * mode, no token, or an unparseable token — SDK defaults apply in those cases.
-   */
-  private static _decodeToken(
-    configuration: FlowConfigurationSnapshot,
-  ): DecodedToken | undefined {
-    if (configuration.config?.allowOfflineMode) return undefined;
-    const token = configuration.network?.config?.token;
-    if (!token || token.length === 0) return undefined;
-    return decodeSmileIDToken(token);
-  }
-
-  private _notify(): void {
-    for (const listener of this._listeners) {
-      try {
-        listener();
-      } catch {
-        // Swallow so one bad listener can't poison the dispatch chain;
-        // the orchestrator-level boundary handles crash reporting.
-      }
-    }
-  }
-}