@smileid/usesmileid 12.0.0-beta01

package/src/presentation/screen/helpers/capture_screen_helpers.ts

@@ -0,0 +1,151 @@
+import { UseSmileIDOverlayState } from "../../state/use_smile_id_overlay_state";
+import type { UseSmileIDOverlayState as OverlayState } from "../../state/use_smile_id_overlay_state";
+import type { UseSmileIDLocalizations } from "../../../l10n/use_smile_id_localizations";
+import type { SiKey } from "../../../l10n/strings_en";
+
+/**
+ * Pure-logic feedback helpers. Feedback travels as a stable `si_*` key
+ * so the coaching animation and copy resolution key off one value.
+ */
+
+/**
+ * Feedback key for a selfie overlay state with explicit guidance.
+ * Lifecycle states return `null` (copy resolved by `mapCaptureUiState`).
+ */
+export function selfieFeedbackKeyFor(state: OverlayState): SiKey | null {
+  switch (state) {
+    case UseSmileIDOverlayState.TOO_CLOSE:
+      return "si_capture_too_close";
+    case UseSmileIDOverlayState.TOO_FAR:
+      return "si_capture_too_far";
+    case UseSmileIDOverlayState.FACE_NOT_CENTERED:
+      return "si_capture_center_face";
+    case UseSmileIDOverlayState.MULTIPLE_FACES:
+      return "si_capture_multiple_faces";
+    case UseSmileIDOverlayState.LOW_LIGHT:
+      return "si_capture_low_light";
+    case UseSmileIDOverlayState.BRIGHT_LIGHT:
+      return "si_capture_bright_light";
+    case UseSmileIDOverlayState.WRONG_ORIENTATION:
+      return "si_capture_rotate_device";
+    case UseSmileIDOverlayState.NOT_SMILING:
+      return "si_capture_smile";
+    case UseSmileIDOverlayState.MOVE_LEFT:
+      return "si_capture_move_left";
+    case UseSmileIDOverlayState.MOVE_RIGHT:
+      return "si_capture_move_right";
+    case UseSmileIDOverlayState.MOVE_UP:
+      return "si_capture_move_higher";
+    case UseSmileIDOverlayState.MOVE_DOWN:
+      return "si_capture_move_lower";
+    default:
+      return null;
+  }
+}
+
+/** Document counterpart of {@link selfieFeedbackKeyFor}. */
+export function documentFeedbackKeyFor(state: OverlayState): SiKey | null {
+  switch (state) {
+    case UseSmileIDOverlayState.DOCUMENT_TOO_CLOSE:
+      return "si_document_too_close";
+    case UseSmileIDOverlayState.DOCUMENT_TOO_FAR:
+      return "si_document_too_far";
+    case UseSmileIDOverlayState.DOCUMENT_NOT_CENTERED:
+      return "si_document_center";
+    case UseSmileIDOverlayState.DOCUMENT_HOLD_STILL:
+      return "si_document_hold_still";
+    default:
+      return null;
+  }
+}
+
+/**
+ * Feedback-key → localized-copy table; unmapped keys fall back to the
+ * initial instruction so the guidance never blanks.
+ */
+const FEEDBACK_COPY: Partial<
+  Record<SiKey, (loc: UseSmileIDLocalizations) => string>
+> = {
+  si_capture_initial_instruction: (loc) => loc.siCaptureInitialInstruction,
+  si_start_capture_instruction: (loc) => loc.siStartCaptureInstruction,
+  si_capture_too_close: (loc) => loc.siCaptureTooClose,
+  si_capture_too_far: (loc) => loc.siCaptureTooFar,
+  si_capture_center_face: (loc) => loc.siCaptureCenterFace,
+  si_capture_multiple_faces: (loc) => loc.siCaptureMultipleFaces,
+  si_capture_low_light: (loc) => loc.siCaptureLowLight,
+  si_capture_bright_light: (loc) => loc.siCaptureBrightLight,
+  si_capture_rotate_device: (loc) => loc.siCaptureRotateDevice,
+  si_capture_smile: (loc) => loc.siCaptureSmile,
+  si_capture_move_left: (loc) => loc.siCaptureMoveLeft,
+  si_capture_move_right: (loc) => loc.siCaptureMoveRight,
+  si_capture_move_higher: (loc) => loc.siCaptureMoveHigher,
+  si_capture_move_lower: (loc) => loc.siCaptureMoveLower,
+  si_capture_ready: (loc) => loc.siCaptureReady,
+  si_capture_hold_steady: (loc) => loc.siCaptureHoldSteady,
+  si_capture_timeout: (loc) => loc.siCaptureTimeout,
+  si_capturing: (loc) => loc.siCapturing,
+  si_selfie_capture_complete: (loc) => loc.siSelfieCaptureComplete,
+  si_selfie_capture_timeout: (loc) => loc.siSelfieCaptureTimeout,
+  si_selfie_capture_unsatisfied: (loc) => loc.siSelfieCaptureUnsatisfied,
+  si_ess_capture_initial_instruction: (loc) =>
+    loc.siEssCaptureInitialInstruction,
+  si_ess_hold_still: (loc) => loc.siEssHoldStill,
+  si_ess_look_left: (loc) => loc.siEssLookLeft,
+  si_ess_look_right: (loc) => loc.siEssLookRight,
+  si_ess_look_up: (loc) => loc.siEssLookUp,
+  si_document_initial_instruction: (loc) => loc.siDocumentInitialInstruction,
+  si_document_ready: (loc) => loc.siDocumentReady,
+  si_document_capturing: (loc) => loc.siDocumentCapturing,
+  si_document_capture_complete: (loc) => loc.siDocumentCaptureComplete,
+  si_document_capture_unsatisfied: (loc) => loc.siDocumentCaptureUnsatisfied,
+  si_document_capture_timeout: (loc) => loc.siDocumentCaptureTimeout,
+  si_document_too_close: (loc) => loc.siDocumentTooClose,
+  si_document_too_far: (loc) => loc.siDocumentTooFar,
+  si_document_center: (loc) => loc.siDocumentCenter,
+  si_document_hold_still: (loc) => loc.siDocumentHoldStill,
+  si_document_gallery_image_too_small: (loc) =>
+    loc.siDocumentGalleryImageTooSmall,
+  si_document_gallery_image_failed: (loc) => loc.siDocumentGalleryImageFailed,
+};
+
+/** Resolve a stable feedback key to the active locale's copy. */
+export function resolveFeedbackCopy(
+  key: SiKey,
+  loc: UseSmileIDLocalizations,
+): string {
+  const resolve = FEEDBACK_COPY[key];
+  return resolve ? resolve(loc) : loc.siCaptureInitialInstruction;
+}
+
+/**
+ * Overlay-state-only copy resolution for callers without a scan state;
+ * `mapCaptureUiState` is the richer path that also handles Enhanced
+ * Smart Selfie copy.
+ */
+export function resolveCaptureFeedback(
+  state: OverlayState,
+  loc: UseSmileIDLocalizations,
+): string {
+  const feedbackKey = selfieFeedbackKeyFor(state);
+  if (feedbackKey) return resolveFeedbackCopy(feedbackKey, loc);
+  switch (state) {
+    case UseSmileIDOverlayState.HEAD_TURN:
+      return loc.siCaptureHoldSteady;
+    case UseSmileIDOverlayState.FACE_DETECTED:
+    case UseSmileIDOverlayState.READY:
+      return loc.siCaptureReady;
+    case UseSmileIDOverlayState.CAPTURING:
+      return loc.siCapturing;
+    default:
+      return loc.siCaptureInitialInstruction;
+  }
+}
+
+/**
+ * Whether the start-capture button is enabled. "Start" begins the
+ * analyzer pipeline (not a snapshot), so it's enabled exactly during
+ * the pre-flight `INSTRUCTION` state — before the pipeline has started.
+ */
+export function isStartCaptureEnabled(state: OverlayState): boolean {
+  return state === UseSmileIDOverlayState.INSTRUCTION;
+}

package/src/presentation/screen/helpers/capture_ui_state.ts

@@ -0,0 +1,298 @@
+import type {
+  ScanHeadTurnDirection,
+  ScanState,
+} from "@smileid/usesmileid_bridge";
+import { ScanStateType } from "@smileid/usesmileid_bridge";
+import { CaptureType } from "../../../core/models/ml_config";
+import { UseSmileIDOverlayState } from "../../state/use_smile_id_overlay_state";
+import type { SiKey } from "../../../l10n/strings_en";
+import { mapScanStateToOverlayState } from "./scan_state_to_overlay_state";
+import {
+  documentFeedbackKeyFor,
+  selfieFeedbackKeyFor,
+} from "./capture_screen_helpers";
+
+/** Immutable per-frame UI snapshot derived from the native `ScanState`. */
+export type UseSmileIDCaptureUiState = {
+  readonly overlayState: UseSmileIDOverlayState;
+  /** Stable si_* key behind the guidance copy and the coaching-animation lookup. */
+  readonly feedbackKey: SiKey;
+  /** 0..1 oval fill; always 0 under Enhanced Smart Selfie. */
+  readonly captureProgress: number;
+  /** Active ESS head-turn direction, null outside a turn. */
+  readonly animationDirection: ScanHeadTurnDirection | null;
+  /**
+   * `true` while the head pose holds the current ESS direction — drives
+   * the grey→green direction arrow. Always `false` outside a head turn.
+   */
+  readonly poseMatched: boolean;
+};
+
+function uiState(
+  overlayState: UseSmileIDOverlayState,
+  feedbackKey: SiKey,
+  captureProgress: number,
+): UseSmileIDCaptureUiState {
+  return {
+    overlayState,
+    feedbackKey,
+    captureProgress,
+    animationDirection: null,
+    poseMatched: false,
+  };
+}
+
+/**
+ * Blocking conditions to surface mid-turn — the user cannot hold the pose
+ * while any holds, so each must show and hide the arrow until it clears.
+ * Order is the precedence orientation > light > position; the native side
+ * sends one feedback code per frame, already dwelled (3 consecutive
+ * frames), so no consumer-side debounce. Smile / motion-blur stay out — a
+ * turning head always moves and they don't block the pose.
+ */
+const ESS_HEAD_TURN_COACHING_KEYS: readonly SiKey[] = [
+  "si_capture_rotate_device",
+  "si_capture_low_light",
+  "si_capture_bright_light",
+  "si_capture_too_far",
+  "si_capture_too_close",
+  "si_capture_center_face",
+];
+
+/** The mid-turn coaching key, or `null` when the turn prompt should show. */
+function essHeadTurnCoachingKey(feedback: string | undefined): SiKey | null {
+  if (feedback === undefined) return null;
+  // Match against the typed set so the result narrows to SiKey without a cast.
+  for (const key of ESS_HEAD_TURN_COACHING_KEYS) {
+    if (key === feedback) return key;
+  }
+  return null;
+}
+
+/**
+ * The oval never fills under Enhanced Smart Selfie — idempotent,
+ * applied once at the mapping's exit.
+ */
+export function withEnhancedLivenessPolicy(
+  state: UseSmileIDCaptureUiState,
+  enableEnhancedLiveness: boolean,
+): UseSmileIDCaptureUiState {
+  return enableEnhancedLiveness && state.captureProgress !== 0
+    ? { ...state, captureProgress: 0 }
+    : state;
+}
+
+/**
+ * Terminal snapshot for a completed selfie scan — single source for
+ * the `finished` mapping and any post-scan fallback.
+ */
+export function scannedUiState(
+  enableEnhancedLiveness: boolean,
+): UseSmileIDCaptureUiState {
+  return withEnhancedLivenessPolicy(
+    uiState(UseSmileIDOverlayState.PROCESSING, "si_selfie_capture_complete", 1),
+    enableEnhancedLiveness,
+  );
+}
+
+/** Terminal snapshot for a completed document scan. */
+export function scannedDocumentUiState(): UseSmileIDCaptureUiState {
+  return uiState(
+    UseSmileIDOverlayState.PROCESSING,
+    "si_document_capture_complete",
+    1,
+  );
+}
+
+/**
+ * Snapshot shown before the first analyzed frame. The overlay stays
+ * IDLE — eagerly mapping the initial scan state is the no-green-flash
+ * regression — while the guidance primes with the flow's initial
+ * instruction.
+ */
+export function preCaptureUiState(
+  captureType: CaptureType,
+  enableEnhancedLiveness: boolean,
+): UseSmileIDCaptureUiState {
+  // Selfie flows (including ESS) show the press-Start copy here; the
+  // ESS primer belongs to the scanning Initial state.
+  const feedbackKey: SiKey =
+    captureType === CaptureType.selfie
+      ? "si_start_capture_instruction"
+      : "si_document_initial_instruction";
+  return uiState(UseSmileIDOverlayState.IDLE, feedbackKey, 0);
+}
+
+/**
+ * True when the native analyzer restarted evaluation: leaving
+ * `unsatisfied`, or `timeout`/`finished` returning to `initial`.
+ */
+export function isSessionBoundary(
+  previous: ScanState,
+  next: ScanState,
+): boolean {
+  if (previous.type === next.type) return false;
+  if (previous.type === ScanStateType.Unsatisfied) return true;
+  return (
+    (previous.type === ScanStateType.Timeout ||
+      previous.type === ScanStateType.Finished) &&
+    next.type === ScanStateType.Initial
+  );
+}
+
+/** Dispatch on capture type — see {@link mapSelfieUiState} / {@link mapDocumentUiState}. */
+export function mapCaptureUiState(
+  scanState: ScanState,
+  captureType: CaptureType,
+  enableEnhancedLiveness: boolean,
+): UseSmileIDCaptureUiState {
+  return captureType === CaptureType.selfie
+    ? mapSelfieUiState(scanState, enableEnhancedLiveness)
+    : mapDocumentUiState(scanState);
+}
+
+/**
+ * Selfie scan-state → UI-state mapping. Enhanced Smart Selfie switches
+ * the copy (initial → head-turn primer; active capture → "Hold
+ * still…") and zeroes the fill.
+ */
+export function mapSelfieUiState(
+  scanState: ScanState,
+  enableEnhancedLiveness: boolean,
+): UseSmileIDCaptureUiState {
+  return withEnhancedLivenessPolicy(
+    selfieUiState(scanState, enableEnhancedLiveness),
+    enableEnhancedLiveness,
+  );
+}
+
+function selfieUiState(
+  scanState: ScanState,
+  enableEnhancedLiveness: boolean,
+): UseSmileIDCaptureUiState {
+  switch (scanState.type) {
+    case ScanStateType.Initial:
+      return uiState(
+        UseSmileIDOverlayState.INSTRUCTION,
+        enableEnhancedLiveness
+          ? "si_ess_capture_initial_instruction"
+          : "si_capture_initial_instruction",
+        0,
+      );
+
+    case ScanStateType.Found: {
+      const overlayState = mapScanStateToOverlayState(
+        scanState,
+        CaptureType.selfie,
+      );
+      const feedbackKey =
+        selfieFeedbackKeyFor(overlayState) ??
+        (enableEnhancedLiveness ? "si_ess_hold_still" : "si_capturing");
+      return uiState(overlayState, feedbackKey, scanState.captureProgress ?? 0);
+    }
+
+    case ScanStateType.Satisfied:
+      // Progress forced to 1 so the ring completes even when the last
+      // interim frame undershot; transient before `finished`.
+      return uiState(
+        UseSmileIDOverlayState.CAPTURING,
+        enableEnhancedLiveness ? "si_ess_hold_still" : "si_capturing",
+        1,
+      );
+
+    case ScanStateType.Unsatisfied:
+      // Unsatisfied collapses onto one requirements-not-met copy —
+      // the per-check `reason` only feeds telemetry, not guidance.
+      return uiState(
+        UseSmileIDOverlayState.FACE_DETECTED,
+        "si_selfie_capture_unsatisfied",
+        0,
+      );
+
+    case ScanStateType.Finished:
+      return scannedUiState(enableEnhancedLiveness);
+
+    case ScanStateType.Timeout:
+      return uiState(UseSmileIDOverlayState.IDLE, "si_capture_timeout", 0);
+
+    case ScanStateType.HeadTurn: {
+      const direction = scanState.currentDirection ?? null;
+      const turnPrompt: SiKey =
+        direction === "left"
+          ? "si_ess_look_left"
+          : direction === "right"
+            ? "si_ess_look_right"
+            : direction === "up"
+              ? "si_ess_look_up"
+              : "si_capture_hold_steady";
+      // A blocking condition owns the copy and hides the arrow — showing
+      // "turn left" over "move closer" would mislead — and pauses pose-match
+      // latching. No coaching key ⇒ the turn prompt + arrow show.
+      const coachingKey = essHeadTurnCoachingKey(scanState.feedback);
+      return {
+        overlayState: UseSmileIDOverlayState.HEAD_TURN,
+        feedbackKey: coachingKey ?? turnPrompt,
+        captureProgress: 0,
+        animationDirection: coachingKey !== null ? null : direction,
+        poseMatched:
+          coachingKey !== null ? false : (scanState.poseMatched ?? false),
+      };
+    }
+  }
+}
+
+/** Document scan-state → UI-state mapping. */
+export function mapDocumentUiState(
+  scanState: ScanState,
+): UseSmileIDCaptureUiState {
+  switch (scanState.type) {
+    case ScanStateType.Initial:
+    // No head-turn phase for documents; a degenerate headTurn maps to
+    // the pre-capture instruction.
+    case ScanStateType.HeadTurn:
+      return uiState(
+        UseSmileIDOverlayState.INSTRUCTION,
+        "si_document_initial_instruction",
+        0,
+      );
+
+    case ScanStateType.Found: {
+      const overlayState = mapScanStateToOverlayState(
+        scanState,
+        CaptureType.document,
+      );
+      const feedbackKey = documentFeedbackKeyFor(overlayState);
+      // No validator warning ⇒ frames are being collected — show the
+      // in-capture copy, not the pre-capture "position your document".
+      return feedbackKey === null
+        ? uiState(
+            UseSmileIDOverlayState.CAPTURING,
+            "si_document_capturing",
+            scanState.captureProgress ?? 0,
+          )
+        : uiState(overlayState, feedbackKey, scanState.captureProgress ?? 0);
+    }
+
+    // Documents collapse satisfied/finished onto the same terminal
+    // snapshot: the still is captured and the screen is moving on.
+    case ScanStateType.Satisfied:
+      return scannedDocumentUiState();
+
+    case ScanStateType.Unsatisfied:
+      return uiState(
+        UseSmileIDOverlayState.IDLE,
+        "si_document_capture_unsatisfied",
+        0,
+      );
+
+    case ScanStateType.Finished:
+      return scannedDocumentUiState();
+
+    case ScanStateType.Timeout:
+      return uiState(
+        UseSmileIDOverlayState.IDLE,
+        "si_document_capture_timeout",
+        0,
+      );
+  }
+}

package/src/presentation/screen/helpers/consent_screen_helpers.ts

@@ -0,0 +1,106 @@
+import type { UseSmileIDLocalizations } from "../../../l10n/use_smile_id_localizations";
+
+/**
+ * Pure-logic helpers for `UseSmileIDConsentScreen`. Extracted so prop
+ * resolution + the subtitle's `{allow}/{smile_id}/{partner}` token
+ * substitution can be unit-tested without an RN renderer.
+ */
+
+export type ConsentRowKey = "contact" | "personal" | "biometric" | "device";
+
+export type ConsentRowSpec = {
+  readonly key: ConsentRowKey;
+  readonly label: string;
+};
+
+/**
+ * Build the four canonical "this may include processing" rows from
+ * the localizations object: Contact → Personal → Biometric → Device.
+ */
+export function buildConsentRows(
+  loc: Pick<
+    UseSmileIDLocalizations,
+    | "siConsentContact"
+    | "siConsentPersonal"
+    | "siConsentBiometric"
+    | "siConsentDevice"
+  >,
+): readonly ConsentRowSpec[] {
+  return [
+    { key: "contact", label: loc.siConsentContact },
+    { key: "personal", label: loc.siConsentPersonal },
+    { key: "biometric", label: loc.siConsentBiometric },
+    { key: "device", label: loc.siConsentDevice },
+  ];
+}
+
+/**
+ * Compose the consent subtitle by substituting the `{allow}`,
+ * `{smile_id}`, and `{partner}` tokens. The Allow / Smile ID values
+ * come from localization (so translations remain coherent); the
+ * partner name is partner-supplied.
+ *
+ * Substitution is done locally because `siConsentSubtitle` is a
+ * non-parameterised getter.
+ */
+export function composeConsentSubtitle(
+  partnerName: string,
+  loc: Pick<
+    UseSmileIDLocalizations,
+    "siConsentSubtitle" | "siConsentSubtitleSmileId" | "siConsentAllow"
+  >,
+): string {
+  return loc.siConsentSubtitle
+    .split("{allow}")
+    .join(loc.siConsentAllow)
+    .split("{smile_id}")
+    .join(loc.siConsentSubtitleSmileId)
+    .split("{partner}")
+    .join(partnerName);
+}
+
+export type SubtitlePart = { readonly text: string; readonly bold: boolean };
+
+/**
+ * Same as [composeConsentSubtitle] but returns the substring chunks
+ * separately, marking each token replacement with `bold: true`. The
+ * screen renders the array as a flow of plain + bold `<Text>` nodes
+ * so partners see the canonical emphasis on `{allow}`, `{smile_id}`,
+ * and `{partner}` without inline styling logic at the call site.
+ */
+export function composeConsentSubtitleParts(
+  partnerName: string,
+  loc: Pick<
+    UseSmileIDLocalizations,
+    "siConsentSubtitle" | "siConsentSubtitleSmileId" | "siConsentAllow"
+  >,
+): readonly SubtitlePart[] {
+  const tokens: ReadonlyArray<{ token: string; value: string }> = [
+    { token: "{allow}", value: loc.siConsentAllow },
+    { token: "{smile_id}", value: loc.siConsentSubtitleSmileId },
+    { token: "{partner}", value: partnerName },
+  ];
+  // Walk the template once, splitting at the next-occurring token and
+  // emitting plain / bold parts in order. Tokens that don't appear in
+  // the template (e.g. a future translation that drops one) are
+  // silently skipped — same fallback the upstream
+  // `composeConsentSubtitle` provides.
+  let remaining = loc.siConsentSubtitle;
+  const out: SubtitlePart[] = [];
+  while (remaining.length > 0) {
+    const next = tokens
+      .map((t) => ({ ...t, index: remaining.indexOf(t.token) }))
+      .filter((t) => t.index >= 0)
+      .sort((a, b) => a.index - b.index)[0];
+    if (!next) {
+      out.push({ text: remaining, bold: false });
+      break;
+    }
+    if (next.index > 0) {
+      out.push({ text: remaining.slice(0, next.index), bold: false });
+    }
+    out.push({ text: next.value, bold: true });
+    remaining = remaining.slice(next.index + next.token.length);
+  }
+  return out;
+}

package/src/presentation/screen/helpers/ess_turn_haptics.ts

@@ -0,0 +1,67 @@
+import * as Haptics from "expo-haptics";
+import type { ScanState } from "@smileid/usesmileid_bridge";
+import { ScanStateType } from "@smileid/usesmileid_bridge";
+
+/** Which haptic a completed Enhanced Smart Selfie head turn warrants. */
+export type EssTurnHaptic = "intermediate" | "final";
+
+/**
+ * Decide which haptic (if any) an Enhanced Smart Selfie head-turn
+ * transition warrants. Fires once per completed turn:
+ *
+ * - `"intermediate"` — one head-turn direction completes and the next
+ *   begins (the requested direction advances).
+ * - `"final"` — the last turn completes and the flow leaves the head-turn
+ *   phase toward capture (`found` / `satisfied` / `finished`).
+ *
+ * Returns `null` for every other transition — crucially including the
+ * reset paths (`headTurn → initial` / `headTurn → timeout`): a reset is
+ * never a completion. `previous` must be the immediately-preceding raw
+ * scan state so the same completion is reported exactly once.
+ */
+export function essTurnHaptic(
+  previous: ScanState,
+  next: ScanState,
+): EssTurnHaptic | null {
+  // Only a transition out of an active, directed head turn can complete one.
+  if (previous.type !== ScanStateType.HeadTurn) return null;
+  if (previous.currentDirection === undefined) return null;
+
+  // The requested direction advanced — the previous turn completed.
+  if (
+    next.type === ScanStateType.HeadTurn &&
+    next.currentDirection !== undefined &&
+    next.currentDirection !== previous.currentDirection
+  ) {
+    return "intermediate";
+  }
+
+  // Leaving the head-turn phase toward capture is the final turn's
+  // completion; `initial` / `timeout` are resets, not completions.
+  if (
+    next.type === ScanStateType.Found ||
+    next.type === ScanStateType.Satisfied ||
+    next.type === ScanStateType.Finished
+  ) {
+    return "final";
+  }
+
+  return null;
+}
+
+/**
+ * Fire the haptic for a completed head turn — a light impact between
+ * turns, a success notification on the final turn. Best-effort UX
+ * feedback: a device without a taptic engine simply no-ops, and a failure
+ * here must never surface as a capture error, so the promise is
+ * intentionally swallowed.
+ */
+export function triggerEssTurnHaptic(kind: EssTurnHaptic): void {
+  const run =
+    kind === "final"
+      ? Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success)
+      : Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);
+  void run.catch(() => {
+    // Haptics are non-essential; ignore taptic-engine / permission failures.
+  });
+}