@myazahq/kyc-sdk-react-native 2.1.0 → 2.3.0

package/src/screens/{BusinessKeyPersonRow.tsx → KeyPersonForm.tsx}

@@ -1,14 +1,13 @@
 import React, { useMemo } from 'react';
-import { Pressable, View } from 'react-native';
+import { View } from 'react-native';
 
-import { radius, spacing } from '../config/theme';
+import { spacing } from '../config/theme';
 import { useTheme } from '../components/runtime';
 import { MyazaText } from '../components/Typography';
 import { MyazaInput } from '../components/MyazaInput';
 import { MyazaSelect } from '../components/MyazaSelect';
 import { CountryField } from '../components/CountryField';
 import type { DialCodeOption } from '../components/DialCodePicker';
-import { Icon } from '../components/Icon';
 import { ALL_REGION_CODES, regionCountryName } from '../config/regions';
 import { isValidContactEmail } from '../config/contact';
 import {
@@ -19,20 +18,18 @@ import {
 import type { KeyPersonRole } from '../types/business';
 
 // ---------------------------------------------------------------------------
-// One editable director/owner row — mirrors the web SDK's BusinessKeyPersonRow
-// and the Flutter row 1:1: bordered card, "PERSON N" header with remove, then
-// full name → role (select) → ownership % → country (full ISO select — a key
-// person's ID can be issued anywhere, not just the registry country) → email.
-// Validation is LIVE per field, like the web: a broken value says so as it is
-// typed, while blank optional fields stay quiet.
+// The key-person FIELDS — full name → role → ownership % → country → email —
+// with the same live per-field validation the old inline row had. No card
+// chrome, no header: this is the body of the add/edit sheet (KeyPersonSheet),
+// which owns the draft state and the save/remove actions.
 // ---------------------------------------------------------------------------
 
-/** Whether the row's role is an ownership one (% is only meaningful then). */
+/** Whether the role is an ownership one (% is only meaningful then). */
 function isOwnerRole(role: KeyPersonRole): boolean {
   return role === 'beneficial_owner' || role === 'shareholder';
 }
 
-/** Every ISO-2 we can name, alphabetical — built once, shared by all rows. */
+/** Every ISO-2 we can name, alphabetical — built once, shared by all mounts. */
 let countryOptions: DialCodeOption[] | null = null;
 function allCountryOptions(): DialCodeOption[] {
   countryOptions ??= [...ALL_REGION_CODES]
@@ -41,66 +38,44 @@ function allCountryOptions(): DialCodeOption[] {
   return countryOptions;
 }
 
-export function BusinessKeyPersonRow({
-  row,
-  index,
+export function KeyPersonForm({
+  entry,
   onChange,
-  onRemove,
   uboThreshold = 25,
+  combinedPctError = null,
 }: {
-  row: KeyPersonEntry;
-  index: number;
+  entry: KeyPersonEntry;
   onChange: (patch: Partial<KeyPersonEntry>) => void;
-  onRemove: () => void;
   /** Ownership % at/above which the server treats a person as a beneficial
    *  owner (the workflow's `keyPeople.ownershipThreshold`, default 25). */
   uboThreshold?: number;
+  /**
+   * Set when this draft's % would push the COMBINED ownership across all
+   * people past 100% — shown on the % field as a warning. It never blocks
+   * saving (the fix may live on a different person); the list's summary and
+   * the disabled Continue enforce the total.
+   */
+  combinedPctError?: string | null;
 }): React.ReactElement {
   const { colors } = useTheme();
   const options = useMemo(allCountryOptions, []);
 
-  const nameInvalid = row.name !== '' && row.name.trim().length < 2;
-  const emailInvalid = row.email.trim() !== '' && !isValidContactEmail(row.email.trim());
-  const pct = row.ownershipPct.trim();
+  const nameInvalid = entry.name !== '' && entry.name.trim().length < 2;
+  const emailInvalid = entry.email.trim() !== '' && !isValidContactEmail(entry.email.trim());
+  const pct = entry.ownershipPct.trim();
   const pctNum = Number(pct);
   const pctInvalid = pct !== '' && (!Number.isFinite(pctNum) || pctNum < 0 || pctNum > 100);
   // Surface the regulatory consequence as feedback: at/above the threshold the
   // server escalates this person to a beneficial owner regardless of the role
   // picked. Quiet when they already chose UBO — nothing new to say.
   const uboHint =
-    !pctInvalid && pct !== '' && pctNum >= uboThreshold && row.role !== 'beneficial_owner';
+    !pctInvalid && pct !== '' && pctNum >= uboThreshold && entry.role !== 'beneficial_owner';
 
   return (
-    <View
-      style={{
-        borderWidth: 1,
-        borderColor: colors.border,
-        borderRadius: radius.sm,
-        padding: spacing.md,
-        marginTop: spacing.sm + 4,
-      }}
-    >
-      <View style={{ flexDirection: 'row', alignItems: 'center', marginBottom: spacing.sm }}>
-        <MyazaText
-          variant="bodySmall"
-          color={colors.textSecondary}
-          style={{ flex: 1, fontWeight: '600', letterSpacing: 0.6 }}
-        >
-          {`PERSON ${index + 1}`}
-        </MyazaText>
-        <Pressable
-          onPress={onRemove}
-          accessibilityRole="button"
-          accessibilityLabel={`Remove person ${index + 1}`}
-          hitSlop={8}
-        >
-          <Icon name="close" size={16} color={colors.textMuted} />
-        </Pressable>
-      </View>
-
+    <View>
       <MyazaInput
         label="Full name"
-        value={row.name}
+        value={entry.name}
         onChangeText={(name) => onChange({ name })}
         placeholder="e.g. Bola Owner"
         // It's a person's name — start every word capitalized.
@@ -113,7 +88,7 @@ export function BusinessKeyPersonRow({
         Role
       </MyazaText>
       <MyazaSelect
-        value={row.role}
+        value={entry.role}
         sheetTitle="Role"
         options={KEY_PERSON_ROLES.map((role) => ({
           value: role,
@@ -125,16 +100,16 @@ export function BusinessKeyPersonRow({
       <View style={{ height: spacing.sm }} />
       <MyazaInput
         label="Ownership % (optional)"
-        value={row.ownershipPct}
+        value={entry.ownershipPct}
         onChangeText={(ownershipPct) => onChange({ ownershipPct })}
-        placeholder={isOwnerRole(row.role) ? 'e.g. 60' : '—'}
+        placeholder={isOwnerRole(entry.role) ? 'e.g. 60' : '—'}
         keyboardType="decimal-pad"
         suffix={
           <MyazaText variant="bodySmall" color={colors.textMuted}>
             %
           </MyazaText>
         }
-        error={pctInvalid ? 'Enter a value between 0 and 100.' : null}
+        error={pctInvalid ? 'Enter a value between 0 and 100.' : combinedPctError}
         helper={
           uboHint
             ? `At ${uboThreshold}% or more, this person counts as a beneficial owner.`
@@ -144,13 +119,16 @@ export function BusinessKeyPersonRow({
 
       <View style={{ height: spacing.sm }} />
       <MyazaText variant="bodySmall" style={{ fontWeight: '600', marginBottom: spacing.xs }}>
-        Country <MyazaText variant="bodySmall" color={colors.textSecondary}>(where their ID was issued)</MyazaText>
+        Country{' '}
+        <MyazaText variant="bodySmall" color={colors.textSecondary}>
+          (where their ID was issued)
+        </MyazaText>
       </MyazaText>
       {/* The SAME sheet as the phone field's dial-code picker (keyboard-aware,
           autofocused search, results pinned above the keys) — minus the dial
           codes. Two country pickers that feel different would read as a bug. */}
       <CountryField
-        value={row.country || null}
+        value={entry.country || null}
         options={options}
         onChange={(country) => onChange({ country })}
       />
@@ -158,7 +136,7 @@ export function BusinessKeyPersonRow({
       <View style={{ height: spacing.sm }} />
       <MyazaInput
         label="Email (optional — used to send their verification link)"
-        value={row.email}
+        value={entry.email}
         onChangeText={(email) => onChange({ email })}
         placeholder="name@company.com"
         keyboardType="email-address"

package/src/screens/KeyPersonSheet.tsx

@@ -0,0 +1,184 @@
+import React, { useEffect, useState } from 'react';
+import {
+  Keyboard,
+  Modal,
+  Platform,
+  Pressable,
+  ScrollView,
+  useWindowDimensions,
+  View,
+} from 'react-native';
+
+import { radius, spacing } from '../config/theme';
+import { useTheme } from '../components/runtime';
+import { MyazaText } from '../components/Typography';
+import { MyazaButton } from '../components/MyazaButton';
+import { Icon } from '../components/Icon';
+import { KeyPersonForm } from './KeyPersonForm';
+import { isKeyPersonRowValid, type KeyPersonEntry } from '../config/keyPeople';
+
+// ---------------------------------------------------------------------------
+// The add/edit key-person sheet. The list step stays a clean stack of summary
+// cards; the FORM lives here — slide-up sheet, grab handle, the five fields,
+// and a pinned primary action. Editing adds a visually separated destructive
+// "Remove this person" beneath the save (never beside it — HIG destructive
+// separation).
+//
+// Keyboard handling mirrors DialCodePicker: the sheet is lifted above the keys
+// and sized against the space that remains, so the focused field is never
+// underneath the keyboard.
+//
+// Save is enabled once the draft is valid. A combined-ownership overshoot
+// WARNS here but never blocks saving — the fix may live on a different
+// person's %, and trapping the user inside this sheet would force them to
+// discard their work to go adjust it.
+// ---------------------------------------------------------------------------
+
+export function KeyPersonSheet({
+  mode,
+  initial,
+  uboThreshold,
+  otherPctTotal,
+  onSave,
+  onRemove,
+  onClose,
+}: {
+  mode: 'add' | 'edit';
+  initial: KeyPersonEntry;
+  uboThreshold?: number;
+  /** Sum of every OTHER person's ownership % — for the combined warning. */
+  otherPctTotal: number;
+  onSave: (entry: KeyPersonEntry) => void;
+  /** Edit mode only — removes the person and closes. */
+  onRemove?: () => void;
+  onClose: () => void;
+}): React.ReactElement {
+  const { colors } = useTheme();
+  const { height: screenHeight } = useWindowDimensions();
+  const [draft, setDraft] = useState<KeyPersonEntry>(initial);
+  const [keyboard, setKeyboard] = useState(0);
+
+  useEffect(() => {
+    // iOS reports 'will' events early enough to resize before the keys land;
+    // Android only emits 'did'.
+    const show = Platform.OS === 'ios' ? 'keyboardWillShow' : 'keyboardDidShow';
+    const hide = Platform.OS === 'ios' ? 'keyboardWillHide' : 'keyboardDidHide';
+    const shown = Keyboard.addListener(show, (e) => setKeyboard(e.endCoordinates.height));
+    const hidden = Keyboard.addListener(hide, () => setKeyboard(0));
+    return () => {
+      shown.remove();
+      hidden.remove();
+    };
+  }, []);
+
+  const available = screenHeight - keyboard;
+  const maxHeight = Math.min(available * 0.92, screenHeight * 0.85);
+
+  const draftPct = Number(draft.ownershipPct);
+  const combinedTotal =
+    draft.ownershipPct.trim() !== '' && Number.isFinite(draftPct)
+      ? otherPctTotal + draftPct
+      : otherPctTotal;
+  const fmtPct = (n: number): string => (Number.isInteger(n) ? String(n) : n.toFixed(1));
+  const combinedPctError =
+    combinedTotal > 100
+      ? `Combined ownership would be ${fmtPct(combinedTotal)}% — over by ${fmtPct(combinedTotal - 100)}%.`
+      : null;
+
+  const canSave = isKeyPersonRowValid(draft) && draft.name.trim().length >= 2;
+
+  return (
+    <Modal visible transparent animationType="slide" onRequestClose={onClose}>
+      {/* Same wrapper as MyazaSelect's option sheet: a flex-end backdrop with
+          the sheet inside it, so the top corners round identically. Tapping
+          the backdrop dismisses; a tap inside the sheet does not. */}
+      <Pressable
+        onPress={onClose}
+        accessibilityLabel="Close"
+        style={{
+          flex: 1,
+          backgroundColor: 'rgba(0,0,0,0.45)',
+          justifyContent: 'flex-end',
+        }}
+      >
+        <Pressable
+          onPress={() => {}}
+          style={{
+            maxHeight,
+            marginBottom: keyboard,
+            backgroundColor: colors.background,
+            borderTopLeftRadius: radius.lg,
+            borderTopRightRadius: radius.lg,
+            overflow: 'hidden',
+          }}
+        >
+        <View
+          style={{
+            alignSelf: 'center',
+            width: 36,
+            height: 4,
+            borderRadius: radius.full,
+            backgroundColor: colors.border,
+            marginTop: spacing.sm,
+          }}
+        />
+        <View
+          style={{
+            flexDirection: 'row',
+            alignItems: 'center',
+            paddingHorizontal: spacing.md,
+            paddingTop: spacing.sm + 4,
+            paddingBottom: spacing.sm,
+          }}
+        >
+          <MyazaText variant="body" style={{ flex: 1, fontWeight: '700' }}>
+            {mode === 'add' ? 'Add a person' : 'Edit person'}
+          </MyazaText>
+          <Pressable onPress={onClose} hitSlop={12} accessibilityRole="button" accessibilityLabel="Close">
+            <Icon name="x" size={20} color={colors.textSecondary} />
+          </Pressable>
+        </View>
+
+        <ScrollView
+          bounces={false}
+          keyboardShouldPersistTaps="handled"
+          contentContainerStyle={{ paddingHorizontal: spacing.md, paddingBottom: spacing.sm }}
+        >
+          <KeyPersonForm
+            entry={draft}
+            onChange={(patch) => setDraft((d) => ({ ...d, ...patch }))}
+            uboThreshold={uboThreshold}
+            combinedPctError={combinedPctError}
+          />
+        </ScrollView>
+
+        <View style={{ paddingHorizontal: spacing.md, paddingTop: spacing.sm, paddingBottom: spacing.lg }}>
+          <MyazaButton
+            label={mode === 'add' ? 'Add person' : 'Save changes'}
+            onPress={canSave ? () => onSave(draft) : undefined}
+            disabled={!canSave}
+          />
+          {mode === 'edit' && onRemove ? (
+            <Pressable
+              onPress={onRemove}
+              accessibilityRole="button"
+              accessibilityLabel="Remove this person"
+              style={({ pressed }) => ({
+                height: 44,
+                alignItems: 'center',
+                justifyContent: 'center',
+                marginTop: spacing.xs,
+                opacity: pressed ? 0.7 : 1,
+              })}
+            >
+              <MyazaText variant="bodySmall" color={colors.error} style={{ fontWeight: '600' }}>
+                Remove this person
+              </MyazaText>
+            </Pressable>
+          ) : null}
+          </View>
+        </Pressable>
+      </Pressable>
+    </Modal>
+  );
+}

package/src/screens/NfcStep.tsx

@@ -151,6 +151,18 @@ export function NfcStep(): React.ReactElement {
         },
       );
       if (!liveRef.current || seq !== readSeqRef.current) return;
+      // Which access protocol opened the session, and why. PACE is new here and
+      // reads over BAC by default, so this line is what distinguishes "the chip
+      // never offered PACE" from "our PACE was attempted and failed" while it
+      // is being proven against real documents. Dev builds only — it is
+      // diagnostics, never user-facing.
+      if (__DEV__) {
+        console.log(
+          `[kyc.nfc] session opened over ${result.chipAuth}` +
+            (result.paceOutcome ? ` (pace: ${result.paceOutcome}` : '') +
+            (result.paceDetail ? ` — ${result.paceDetail})` : result.paceOutcome ? ')' : ''),
+        );
+      }
       store.getState().setChipData(result);
       setResult(result);
       setPhase('done');

package/src/screens/QuestionnaireField.tsx

@@ -33,22 +33,35 @@ export function QuestionnaireFieldView({
   field,
   value,
   currencyValue,
+  detailValue,
   error,
   onChange,
   onCurrencyChange,
+  onDetailChange,
 }: {
   field: FieldDef;
   value: QuestionnaireAnswerValue | undefined;
   /** money only: the `<key>_currency` companion answer. */
   currencyValue?: string;
+  /** choice fields only: the `<key>_other` companion answer. */
+  detailValue?: string;
   error?: string;
   onChange: (value: QuestionnaireAnswerValue | undefined) => void;
   onCurrencyChange: (currency: string) => void;
+  onDetailChange?: (detail: string | undefined) => void;
 }): React.ReactElement {
   const { colors } = useTheme();
 
   const isPlainInput = field.type === 'text' || field.type === 'number';
 
+  // The chosen option that is not an answer on its own ("Other"). Covers both
+  // select (a single value) and multiselect (a list).
+  const detailOption = (field.options ?? []).find(
+    (o) =>
+      o.requiresDetail &&
+      (Array.isArray(value) ? value.includes(o.value) : value === o.value),
+  );
+
   return (
     <View style={{ marginBottom: spacing.lg }}>
       <FieldLabel
@@ -143,6 +156,23 @@ export function QuestionnaireFieldView({
           })
         : null}
 
+      {/* Free text behind an "Other" choice. Always required once that option
+          is picked: an unexplained "Other" is the answer a compliance reviewer
+          most needs spelled out. */}
+      {detailOption ? (
+        <View style={{ marginTop: spacing.sm }}>
+          <MyazaInput
+            label={detailOption.detailLabel || 'Please specify'}
+            value={detailValue ?? ''}
+            maxLength={200}
+            placeholder={
+              detailOption.detailPlaceholder || `Tell us more about "${detailOption.label}"`
+            }
+            onChangeText={(text: string) => onDetailChange?.(text || undefined)}
+          />
+        </View>
+      ) : null}
+
       {/* Inputs draw their own error; the rest need one underneath. */}
       {error && !isPlainInput && field.type !== 'money' ? (
         <MyazaText variant="bodySmall" color={colors.error} style={{ marginTop: spacing.xs }}>

package/src/screens/QuestionnaireStep.tsx

@@ -4,7 +4,7 @@ import { View } from 'react-native';
 import { spacing } from '../config/theme';
 import { useKyc, useKycConfig, useKycStore } from '../components/runtime';
 import { MyazaButton } from '../components/MyazaButton';
-import { currencyKeyFor, validateQuestionnaire } from '../config/questionnaire';
+import { currencyKeyFor, otherKeyFor, validateQuestionnaire } from '../config/questionnaire';
 import { QuestionnaireFieldView } from './QuestionnaireField';
 import type { QuestionnaireAnswerValue } from '../types/workflow';
 
@@ -63,9 +63,11 @@ export function QuestionnaireStep(): React.ReactElement {
           field={field}
           value={answers[field.key]}
           currencyValue={answers[currencyKeyFor(field)] as string | undefined}
+          detailValue={answers[otherKeyFor(field)] as string | undefined}
           error={errors[field.key] || undefined}
           onChange={(value) => setAnswer(field.key, value)}
           onCurrencyChange={(currency) => setAnswer(currencyKeyFor(field), currency)}
+          onDetailChange={(detail) => setAnswer(otherKeyFor(field), detail)}
         />
       ))}
 

package/src/screens/nfc/NfcSuccessPanel.tsx

@@ -1,4 +1,4 @@
-import React, { useState } from 'react';
+import React, { useMemo, useState } from 'react';
 import { Image, View } from 'react-native';
 
 import { spacing } from '../../config/theme';
@@ -8,7 +8,7 @@ import { MyazaButton } from '../../components/MyazaButton';
 import { Icon } from '../../components/Icon';
 import { useChipPortrait } from './useChipPortrait';
 import { NfcScannedSummary } from './NfcScannedSummary';
-import type { EmrtdReadResult } from '../../emrtd';
+import { parseDg1, type EmrtdReadResult } from '../../emrtd';
 import type { MrzScan } from '../../mrz/parse';
 
 // ---------------------------------------------------------------------------
@@ -41,7 +41,12 @@ export function NfcSuccessPanel({
   // component rejects) must degrade to the generic mark, not an empty circle.
   const [portraitBroken, setPortraitBroken] = useState(false);
   const portrait = portraitBroken ? null : portraitUri;
-  const name = [mrz?.firstName, mrz?.lastName].filter(Boolean).join(' ');
+  // Once the chip has been read, IT is the source — see emrtd/dg1.ts. The
+  // camera scan stays as the fallback for a chip whose DG1 we could not parse,
+  // so a read that otherwise worked still shows something.
+  const chip = useMemo(() => parseDg1(result.dg1), [result.dg1]);
+  const holder = chip ?? mrz;
+  const name = [holder?.firstName, holder?.lastName].filter(Boolean).join(' ');
 
   return (
     <View style={{ alignItems: 'center' }}>
@@ -132,12 +137,14 @@ export function NfcSuccessPanel({
       ) : null}
 
       {/* What was read, shown back — the same card the pre-read screen uses, so
-          the user checks the same two fields against the printed page. */}
-      {mrz ? (
+          the user checks the same two fields against the printed page. Before
+          the read that card can only show the camera's guess; here it shows the
+          chip's own values, which is both correct and a stronger check. */}
+      {holder ? (
         <>
           <View style={{ height: spacing.lg }} />
           <View style={{ alignSelf: 'stretch' }}>
-            <NfcScannedSummary scan={mrz} />
+            <NfcScannedSummary scan={holder} />
           </View>
         </>
       ) : null}

package/src/services/deviceMetadata.ts

@@ -4,6 +4,7 @@
 // `utils/device-metadata.ts` and the Flutter SDK's `device_metadata_service.dart`.
 
 import { OS } from '../utils/platform';
+import { getStepLog } from '../lib/step-log';
 
 export const SDK_TYPE = 'react-native' as const;
 
@@ -14,7 +15,7 @@ export type DeviceType = 'mobile' | 'tablet' | 'desktop' | 'unknown';
  * Single source of truth for the SDK version — also used by `services/api.ts`
  * for the `X-SDK-Version` header. Keep in sync with `package.json`.
  */
-export const SDK_VERSION = '2.1.0';
+export const SDK_VERSION = '2.3.0';
 
 export interface ReactNativeDeviceMetadata {
   sdkType: 'react-native';
@@ -181,5 +182,12 @@ export function collectDeviceMetadata(): ReactNativeDeviceMetadata {
     meta.locale = locales[0]?.languageTag;
   }
 
+  // Step journey recorded during the session — powers the dashboard's
+  // verification timeline. See lib/step-log.
+  const stepLog = getStepLog();
+  if (stepLog) {
+    (meta as ReactNativeDeviceMetadata & { stepLog?: unknown }).stepLog = stepLog;
+  }
+
   return meta;
 }

package/src/store/derive.ts

@@ -29,6 +29,13 @@ import type { KYCStep, SupportedCountry } from '../types/config';
 import type { KycState } from './state';
 
 export function livenessEnabled(state: KycState): boolean {
+  // Presence Intelligence off ⇒ no selfie step at all. This is the builder's
+  // "Presence Intelligence step" switch (`enableSelfie`), and it outranks the
+  // liveness-gesture question below: with no selfie there is nothing to run
+  // gestures against. Checked first for that reason, and because omitting it
+  // was why turning the step off in the workflow changed nothing here while it
+  // worked on web.
+  if (state.config.enableSelfie === false) return false;
   // Consumer baseline: liveness is on unless explicitly disabled.
   if (state.config.enableLiveness === false) return false;
   const idType = state.selectedIdType;

package/src/store/kycStore.ts

@@ -27,6 +27,7 @@ import {
   type KycStore,
 } from './state';
 import { nextStepAfter, nfcDecision, previousStepBefore } from './derive';
+import { recordStep, resetStepLog } from '../lib/step-log';
 import { buildVerifyRequest } from './submit';
 import { applicantMediaCaptured, buildApplicantVerifyRequest } from './submitApplicant';
 
@@ -54,7 +55,7 @@ export function createKycStore(
   const baseUrl = resolveBaseUrl(config.apiKey, config.devUrl);
   const api = createKYCApi(baseUrl, config.apiKey);
 
-  return createStore<KycState>((set, get) => {
+  const store = createStore<KycState>((set, get) => {
     function emitStepChange(step: KYCStep): void {
       config.onStepChange?.(step);
     }
@@ -354,6 +355,11 @@ export function createKycStore(
       },
 
       reset() {
+        // Fresh step journey per session; the explicit record covers a store
+        // already sitting on 'consent' (the subscribe below only fires on
+        // change, and recordStep dedupes if it fires too).
+        resetStepLog();
+        recordStep('consent');
         set({
           currentStep: 'consent',
           selectedCountry: null,
@@ -383,6 +389,24 @@ export function createKycStore(
       },
     };
   });
+
+  // Step journey log — records every step the user reaches (the subscription
+  // catches ALL currentStep writes, whatever action made them; recordStep
+  // collapses consecutive duplicates). Rides the submission as
+  // metadata.device.stepLog for the dashboard timeline.
+  store.subscribe((s, prev) => {
+    if (s.currentStep !== prev.currentStep) recordStep(s.currentStep);
+  });
+
+  // A fresh store IS a fresh session: the runtime provider creates one per
+  // modal launch and reset() is NOT part of the open path, so the journey
+  // starts here — and the opening step must be recorded explicitly (the
+  // subscription above only fires on CHANGE, and a new store already sits on
+  // 'consent').
+  resetStepLog();
+  recordStep(store.getState().currentStep);
+
+  return store;
 }
 
 // Re-export the flow helpers for tests + screens that need to reason about

package/src/types/config.ts

@@ -61,6 +61,9 @@ export type KYCStep =
 // Client-side SDK config  (MyazaKYC.show() / useMyazaKYC options)
 // ---------------------------------------------------------------------------
 
+/** How flow progress is drawn — see {@link MyazaKYCConfig.progressStyle}. */
+export type ProgressStyle = 'steps' | 'bar';
+
 export interface MyazaKYCConfig<C extends SupportedCountry = SupportedCountry> {
   /**
    * Bearer token. The key prefix is the single source of truth for the
@@ -203,6 +206,20 @@ export interface MyazaKYCConfig<C extends SupportedCountry = SupportedCountry> {
   /** Show a light/dark mode toggle button inside the modal header. Default `true`. */
   showThemeToggle?: boolean;
 
+  /**
+   * How progress through the flow is drawn in the header.
+   *
+   *   • `'steps'` (default) — numbered circles, one per step, connected. Shows
+   *     WHICH step you are on and how many there are, and collapses to a window
+   *     when they no longer fit.
+   *   • `'bar'` — a single thin bar pinned to the bottom edge of the header.
+   *     Quieter, and unaffected by step count, so it suits long flows and hosts
+   *     who would rather the chrome said less.
+   *
+   * Both convey the same fraction; the choice is how much room it takes.
+   */
+  progressStyle?: ProgressStyle;
+
   /**
    * Hide the close (X) button and block all user-initiated dismissal of the
    * sheet — the X button, Android hardware back, and the iOS swipe-down drag.

package/src/types/workflow.ts

@@ -82,6 +82,16 @@ export interface PhoneVerificationConfig {
 export interface QuestionnaireFieldOption {
   value: string;
   label: string;
+  /**
+   * Marks a choice that is not an answer on its own — an "Other". Selecting it
+   * reveals a required free-text input, stored as the `<key>_other` companion
+   * answer (the same shape as a money field's `<key>_currency`).
+   */
+  requiresDetail?: boolean;
+  /** Label for the detail input (default "Please specify"). */
+  detailLabel?: string;
+  /** Placeholder for the detail input (default `Tell us more about "<label>"`). */
+  detailPlaceholder?: string;
 }
 
 export interface QuestionnaireField {