@smileid/usesmileid 12.0.0 → 12.0.1

package/src/presentation/components/__tests__/use_smile_id_enhanced_smart_selfie_clip.test.tsx

@@ -8,8 +8,9 @@ import {
 import { AccessibilityInfo } from "react-native";
 import {
   UseSmileIDEnhancedSmartSelfieClip,
-  ENHANCED_SMART_SELFIE_ANIMATION_SIZE,
+  ENHANCED_SMART_SELFIE_ARROW_FIT,
 } from "../use_smile_id_enhanced_smart_selfie_clip";
+import { FaceOvalDefaults } from "../face_oval_defaults";
 import {
   ENHANCED_SMART_SELFIE_ANIMATION_SPEED,
   ENHANCED_SMART_SELFIE_TOTAL_FRAMES,
@@ -195,7 +196,7 @@ describe("UseSmileIDEnhancedSmartSelfieClip", () => {
   });
 
   describe("positioning", () => {
-    it("produces a container sized to ENHANCED_SMART_SELFIE_ANIMATION_SIZE", async () => {
+    it("sizes the container to the oval width times the arrow-fit factor", async () => {
       const tree = renderClip({ pingPong: false });
       await act(async () => {
         await Promise.resolve();
@@ -209,8 +210,12 @@ describe("UseSmileIDEnhancedSmartSelfieClip", () => {
       );
       expect(container).toBeDefined();
       const style = container!.props.style as { width: number; height: number };
-      expect(style.width).toBe(ENHANCED_SMART_SELFIE_ANIMATION_SIZE);
-      expect(style.height).toBe(ENHANCED_SMART_SELFIE_ANIMATION_SIZE);
+      const expectedSize =
+        BASE_CONTAINER_WIDTH *
+        FaceOvalDefaults.ovalWidthRatio *
+        ENHANCED_SMART_SELFIE_ARROW_FIT;
+      expect(style.width).toBe(expectedSize);
+      expect(style.height).toBe(expectedSize);
     });
   });
 

package/src/presentation/components/__tests__/use_smile_id_instructions_hero.test.tsx

@@ -78,6 +78,50 @@ describe("UseSmileIDInstructionsHero", () => {
     }
   });
 
+  it("pins oval-less heroes to the software Lottie engine on iOS", () => {
+    // lottie-ios's CA engine mis-renders the doc heroes' track mattes, so
+    // oval-less heroes must pin renderMode SOFTWARE on iOS.
+    const docTree = render(
+      <UseSmileIDInstructionsHero
+        source={SELFIE_HERO_ANIMATION}
+        showOval={false}
+        showOvalProgress={false}
+      />,
+    );
+    const docHero = docTree.root.findByProps({
+      testID: "si_instructions_hero",
+    });
+    act(() => {
+      docHero.props.onLayout({
+        nativeEvent: { layout: { width: 390, height: 600 } },
+      });
+    });
+    expect(docTree.root.findByType(AnimatedLottieView).props.renderMode).toBe(
+      "SOFTWARE",
+    );
+    act(() => docTree.unmount());
+
+    const ovalTree = render(
+      <UseSmileIDInstructionsHero
+        source={SELFIE_HERO_ANIMATION}
+        showOval
+        showOvalProgress={false}
+      />,
+    );
+    const ovalHero = ovalTree.root.findByProps({
+      testID: "si_instructions_hero",
+    });
+    act(() => {
+      ovalHero.props.onLayout({
+        nativeEvent: { layout: { width: 390, height: 600 } },
+      });
+    });
+    expect(
+      ovalTree.root.findByType(AnimatedLottieView).props.renderMode,
+    ).toBeUndefined();
+    act(() => ovalTree.unmount());
+  });
+
   it("gives the document card hero explicit dimensions (no intrinsic-size flash)", () => {
     const tree = render(
       <UseSmileIDInstructionsHero

package/src/presentation/components/use_smile_id_enhanced_smart_selfie_clip.tsx

@@ -13,8 +13,11 @@ import {
 export const ESS_ALL_DIRECTIONS_ANIMATION =
   require("../assets/si_ess_animation_all_directions.json") as AnimationObject;
 
-/** Square box the Enhanced Smart Selfie cues render in, centred on the oval. */
-export const ENHANCED_SMART_SELFIE_ANIMATION_SIZE = 383;
+/**
+ * Box width as a multiple of the oval width; the baked arrow tips touch the
+ * oval boundary at ≈1.19× — keep this factor below that.
+ */
+export const ENHANCED_SMART_SELFIE_ARROW_FIT = 1.15;
 /** Nudge so the composition's face lands on the oval centre. */
 export const VERTICAL_ALIGNMENT_OFFSET = -15;
 
@@ -46,7 +49,10 @@ export function UseSmileIDEnhancedSmartSelfieClip(
     return null;
   }
 
-  const size = ENHANCED_SMART_SELFIE_ANIMATION_SIZE;
+  const size =
+    containerWidth *
+    FaceOvalDefaults.ovalWidthRatio *
+    ENHANCED_SMART_SELFIE_ARROW_FIT;
   const ovalCenterY = containerHeight * FaceOvalDefaults.ovalCenterYRatio;
 
   const containerStyle = {

package/src/presentation/components/use_smile_id_instructions_hero.tsx

@@ -2,6 +2,7 @@ import { useEffect, useRef, useState } from "react";
 import {
   Animated,
   Easing,
+  Platform,
   StyleSheet,
   View,
   type LayoutChangeEvent,
@@ -160,6 +161,13 @@ export function UseSmileIDInstructionsHero({
   // motion is reduced; otherwise let it play on its own clock (autoPlay+loop).
   const lottieDrivenByProgress = showOvalProgress || reducedMotion;
 
+  // lottie-ios's Core Animation engine mis-renders the document heroes' track mattes,
+  // so oval-less heroes use the main-thread engine on iOS; Android keeps its default.
+  const renderModeProps =
+    Platform.OS === "ios" && !showOval
+      ? ({ renderMode: "SOFTWARE" } as const)
+      : {};
+
   // Inset the ring by half the stroke so it isn't clipped at the SVG edge.
   const ellipseProps = {
     cx: ovalWidth / 2,
@@ -196,6 +204,7 @@ export function UseSmileIDInstructionsHero({
               autoPlay={!lottieDrivenByProgress}
               loop={!lottieDrivenByProgress}
               {...(lottieDrivenByProgress ? { progress: heroProgress } : {})}
+              {...renderModeProps}
               resizeMode="contain"
               style={{ width: cardWidth, height: cardHeight }}
             />
@@ -266,6 +275,7 @@ export function UseSmileIDInstructionsHero({
               autoPlay={!lottieDrivenByProgress}
               loop={!lottieDrivenByProgress}
               {...(lottieDrivenByProgress ? { progress: heroProgress } : {})}
+              {...renderModeProps}
               style={{
                 position: "absolute",
                 width: animationSize,

package/src/presentation/flow/__tests__/document_flow_navigation.test.ts

@@ -74,15 +74,15 @@ describe("FlowNavigationManager — document per-side preview loop", () => {
       true,
     );
 
-    const passportFlow = buildScreens((screens) => {
+    const greenBookFlow = buildScreens((screens) => {
       screens.capture((capture) => {
         capture.captureType = CaptureType.document;
         capture.document((document) => {
-          document.documentType = DocumentType.Passport; // no back side
+          document.documentType = DocumentType.SouthAfricaGreenBook; // no back side
         });
       });
     });
-    expect(makeManager(passportFlow).documentCapturesBack()).toBe(false);
+    expect(makeManager(greenBookFlow).documentCapturesBack()).toBe(false);
   });
 
   it("after the FRONT preview, routes back to the document capture for the BACK", () => {

package/src/presentation/flow/__tests__/flow_navigation_manager.test.ts

@@ -602,6 +602,55 @@ describe("FlowNavigationManager — submission lifecycle", () => {
     expect(manager.jobSubmissionState.kind).toBe("success");
   });
 
+  it("retrySubmission double-trigger fires exactly one new submission", async () => {
+    // Concrete scenario: the processing screen's retry button is
+    // double-tapped after a failed submission. The second tap must not
+    // reset the in-flight `loading` latch and launch a duplicate job.
+    const repository = new StubRepository();
+    repository.result = failure(new Error("transient"));
+    const manager = makeManager(
+      buildScreens((screens) => screens.processing()),
+      vi.fn(),
+      {
+        enhancedKYCParams: {
+          idType: "BVN",
+          idNumber: "1",
+          country: "NG",
+        },
+        userDetails: SAMPLE_USER_DETAILS,
+        network: {
+          config: {
+            jobType: JobType.enhancedKyc,
+            token: "k",
+            partnerConfig: {
+              partnerId: "p",
+              callbackUrl: "",
+              useSandbox: true,
+            },
+          },
+        },
+      },
+      repository,
+    );
+
+    // Initial attempt fails, leaving the retry affordance visible.
+    manager.beginSubmissionIfNeeded();
+    await flushMicrotasks();
+    expect(manager.jobSubmissionState.kind).toBe("failure");
+    expect(repository.received).toHaveLength(1);
+
+    // The retried submission stays in flight so both taps land while
+    // the request is loading.
+    repository.manual = true;
+    manager.retrySubmission();
+    manager.retrySubmission(); // double-tap — ignored while in flight
+
+    await flushMicrotasks();
+    expect(manager.jobSubmissionState.kind).toBe("loading");
+    // Exactly one new submission: the initial failure plus one retry.
+    expect(repository.received).toHaveLength(2);
+  });
+
   it("does not update state if the manager is disposed mid-submission", async () => {
     const repository = new StubRepository();
     repository.manual = true;

package/src/presentation/flow/dsl/builder/__tests__/config_builder.test.ts

@@ -0,0 +1,25 @@
+import { describe, it, expect } from "vitest";
+import * as ScreenOrientation from "expo-screen-orientation";
+import { GlobalPrivacyControl } from "../../../../../core/models/global_privacy_control";
+import { UseSmileIDConfigBuilder } from "../config_builder";
+
+describe("UseSmileIDConfigBuilder", () => {
+  it("snapshots the documented defaults", () => {
+    expect(new UseSmileIDConfigBuilder().build()).toEqual({
+      enableCrashReporting: true,
+      enableDebugMode: false,
+      allowOfflineMode: false,
+      globalPrivacyControl: GlobalPrivacyControl.OptOut,
+      exitOrientations: ScreenOrientation.OrientationLock.PORTRAIT_UP,
+    });
+  });
+
+  it("carries an overridden exit orientation lock into the snapshot", () => {
+    const builder = new UseSmileIDConfigBuilder();
+    builder.exitOrientations = ScreenOrientation.OrientationLock.DEFAULT;
+
+    expect(builder.build().exitOrientations).toBe(
+      ScreenOrientation.OrientationLock.DEFAULT,
+    );
+  });
+});

package/src/presentation/flow/dsl/builder/config_builder.ts

@@ -1,4 +1,6 @@
+import * as ScreenOrientation from "expo-screen-orientation";
 import type { ConfigOptions } from "../../../../core/models/config";
+import { GlobalPrivacyControl } from "../../../../core/models/global_privacy_control";
 
 /**
  * `b.config((c) => { c.enableCrashReporting = false; ... })`
@@ -26,11 +28,30 @@ export class UseSmileIDConfigBuilder {
    */
   allowOfflineMode = false;
 
+  /**
+   * Consent posture for every session (`global_privacy_control`). Defaults
+   * to `GlobalPrivacyControl.OptOut` — the opt-out consent layout is
+   * enforced universally and regional detection is ignored. Set
+   * `GlobalPrivacyControl.OptIn` to keep the legacy regional mechanics
+   * (opt-in inside the EU, opt-out elsewhere).
+   */
+  globalPrivacyControl: GlobalPrivacyControl = GlobalPrivacyControl.OptOut;
+
+  /**
+   * Orientation lock applied when a capture screen leaves the screen.
+   * Defaults to portrait-up; set `ScreenOrientation.OrientationLock.DEFAULT`
+   * if your app supports more than one orientation.
+   */
+  exitOrientations: ScreenOrientation.OrientationLock =
+    ScreenOrientation.OrientationLock.PORTRAIT_UP;
+
   build(): ConfigOptions {
     return Object.freeze({
       enableCrashReporting: this.enableCrashReporting,
       enableDebugMode: this.enableDebugMode,
       allowOfflineMode: this.allowOfflineMode,
+      globalPrivacyControl: this.globalPrivacyControl,
+      exitOrientations: this.exitOrientations,
     });
   }
 }

package/src/presentation/flow/dsl/builder/screens_builder.ts

@@ -89,8 +89,9 @@ export class InstructionsConfigBuilder {
 
 export class SelfieCaptureConfigBuilder {
   /**
-   * When true, lets an assisting agent flip to the rear camera to capture
-   * the subject. Defaults to false.
+   * When true, the whole selfie session captures on the rear camera so an
+   * assisting agent can point it at the subject. Cannot be combined with
+   * {@link enableEnhancedLiveness}.
    */
   allowAgentMode = false;
   /**
@@ -180,10 +181,6 @@ export class PreviewConfigBuilder {
    * true.
    */
   showAttribution = true;
-  /** Provides a custom continue button in place of the default. */
-  continueButton?: ButtonSlot;
-  /** Provides a custom cancel button in place of the default. */
-  cancelButton?: ButtonSlot;
 }
 
 export class ProcessingConfigBuilder {

package/src/presentation/flow/flow_navigation_manager.ts

@@ -693,9 +693,14 @@ export class FlowNavigationManager {
     void this._submit();
   }
 
-  /** Reset to `notAttempted` and re-fire submission (processing screen's onRetry). */
+  /**
+   * 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();
   }

package/src/presentation/flow/model/instructions_defaults.ts

@@ -31,7 +31,7 @@ export const SELFIE_HERO_ANIMATION =
   require("../../assets/si_selfie_hero_animation.json") as AnimationObject;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 export const ESS_HERO_ANIMATION =
-  require("../../assets/si_ess_animation_all_directions.json") as AnimationObject;
+  require("../../assets/si_ess_all_directions_hero_animation.json") as AnimationObject;
 
 // Document hero animations — per-document-type front instruction heroes, plus
 // the back-of-ID (flip) hero shown on the back-capture interstitial.

package/src/presentation/flow/screen/orchestrated_capture_screen.tsx

@@ -75,10 +75,15 @@ export function OrchestratedCaptureScreen({
   // selfie to portrait. The flip interstitial is a portrait instruction screen,
   // so it must NOT inherit the document's landscape lock — force portrait while
   // it shows, then revert to the document orientation for the back capture.
+  const exitOrientations =
+    navigationManager.configuration.config?.exitOrientations;
   useCaptureOrientationLock(
     captureType === CaptureType.document && !showBackInstructions
       ? (documentType?.orientation ?? "Landscape")
       : "Portrait",
+    {
+      ...(exitOrientations !== undefined ? { exitLock: exitOrientations } : {}),
+    },
   );
 
   // Selfie also pushes the registry-built wire FaceConfig; documents have no
@@ -184,6 +189,7 @@ export function OrchestratedCaptureScreen({
             enableEnhancedLiveness={
               configuration.selfieConfig?.enableEnhancedLiveness ?? false
             }
+            allowAgentMode={configuration.selfieConfig?.allowAgentMode ?? false}
             {...(captureType === CaptureType.document && documentConfig
               ? {
                   // Type ratio → partner override → orientation default; matches
@@ -261,9 +267,18 @@ export function OrchestratedCaptureScreen({
                     ...(fingerprint ? { fingerprint } : {}),
                   }),
                 )
-                .then(() =>
-                  SmileExifTagger.finalize(primary, imageTypeForCapture),
-                )
+                .then(async () => {
+                  await SmileExifTagger.finalize(primary, imageTypeForCapture);
+                  // Liveness frames ship in the same submission, so they need the tag too.
+                  await Promise.all(
+                    livenessUrls.map((livenessUrl) =>
+                      SmileExifTagger.finalize(livenessUrl, ImageType.Liveness),
+                    ),
+                  );
+                })
+                // Tagging is fail-open: a rejection must not become an unhandled
+                // rejection, and navigation still runs in `finally`.
+                .catch(() => undefined)
                 .finally(async () => {
                   if (captureType === CaptureType.selfie) {
                     navigationManager.setCapturedSelfie(primary, livenessUrls);

package/src/presentation/flow/screen/orchestrated_consent_screen.tsx

@@ -2,6 +2,7 @@ import type { ConsentConfigBuilder } from "../dsl/builder/screens_builder";
 import type { ConsentInformation } from "../../../core/models/params";
 import { UseSmileIDCrashReporting } from "@smileid/usesmileid_bridge";
 import { ConsentDeniedException } from "../../../core/exception";
+import { GlobalPrivacyControl } from "../../../core/models/global_privacy_control";
 import { UseSmileIDConsentScreen } from "../../screen/use_smile_id_consent_screen";
 import { UseSmileIDOrchestratedScreenHost } from "./use_smile_id_orchestrated_screen_host";
 
@@ -25,6 +26,10 @@ export function OrchestratedConsentScreen({
       content={({ navigationManager, onNavigateNext }) => (
         <UseSmileIDConsentScreen
           partnerName={configuration.partnerName}
+          globalPrivacyControl={
+            navigationManager.configuration.config?.globalPrivacyControl ??
+            GlobalPrivacyControl.OptOut
+          }
           {...(configuration.partnerIcon !== undefined
             ? { partnerIcon: configuration.partnerIcon }
             : {})}

package/src/presentation/flow/screen/orchestrated_preview_screen.tsx

@@ -50,18 +50,6 @@ export function OrchestratedPreviewScreen({
             {...(navigationManager.captured.selfiePath !== undefined
               ? { capturedSelfiePath: navigationManager.captured.selfiePath }
               : {})}
-            {...(configuration.continueButton
-              ? {
-                  continueButton: ({ onClick }: { onClick: () => void }) =>
-                    configuration.continueButton?.({ onClick, enabled: true }),
-                }
-              : {})}
-            {...(configuration.cancelButton
-              ? {
-                  cancelButton: ({ onClick }: { onClick: () => void }) =>
-                    configuration.cancelButton?.({ onClick, enabled: true }),
-                }
-              : {})}
             onAccept={onNavigateNext}
             onReject={() => {
               if (configuration.allowRetake) onBack();

package/src/presentation/flow/use_smile_id_flow.tsx

@@ -39,8 +39,8 @@ import {
  * whether the partner constructs `network.retry` explicitly or not.
  */
 const DEFAULT_RETRY: RetryConfig = Object.freeze({
-  maxAttempts: 3,
-  strategy: RetryStrategy.exponential,
+  maxAttempts: 1,
+  strategy: RetryStrategy.none,
   initialDelay: 1,
   multiplier: 2,
   maxDelay: 32,
@@ -147,6 +147,10 @@ export function FlowSuccessRenderer({
   useUseSmileIDFonts();
   const enableCrashReporting =
     configuration.config?.enableCrashReporting !== false;
+  // Sandbox sessions are test traffic and must not pollute the production
+  // Sentry project; the reporter also drops debug bundles internally.
+  const useSandbox =
+    configuration.network?.config?.partnerConfig?.useSandbox === true;
 
   // Per-flow session id used as the Sentry user-id so every event
   // captured during this verification flow correlates under one issue
@@ -160,7 +164,10 @@ export function FlowSuccessRenderer({
 
   useEffect(() => {
     if (enableCrashReporting) {
-      UseSmileIDCrashReporting.enable();
+      // Tear down any prior client first so a changed useSandbox flag takes
+      // effect — enable() short-circuits when already enabled.
+      UseSmileIDCrashReporting.disable();
+      UseSmileIDCrashReporting.enable({ useSandbox });
       UseSmileIDCrashReporting.setUserId(flowSessionIdRef.current!);
       UseSmileIDCrashReporting.captureBreadcrumb({
         category: "flow.navigation",
@@ -170,7 +177,7 @@ export function FlowSuccessRenderer({
     return () => {
       UseSmileIDCrashReporting.disable();
     };
-  }, [enableCrashReporting]);
+  }, [enableCrashReporting, useSandbox]);
 
   // `onResult` lives in a ref so the manager's `onExit` closure
   // captures the latest partner callback without recreating the

package/src/presentation/flow/validation/__tests__/flow_validator.test.ts

@@ -20,7 +20,10 @@ import {
   InvalidJobTypeScreenConfigException,
   MissingMLConfigurationBlockException,
 } from "../../../../core/exception/job_validation_exceptions";
-import { InvalidDocumentCaptureConfigException } from "../../../../core/exception/capture_validation_exceptions";
+import {
+  AgentModeWithEnhancedLivenessException,
+  InvalidDocumentCaptureConfigException,
+} from "../../../../core/exception/capture_validation_exceptions";
 import {
   runDocumentVerificationParamsValidation,
   runEnhancedDocumentVerificationParamsValidation,
@@ -189,6 +192,63 @@ describe("FlowValidator — document capture config", () => {
   });
 });
 
+describe("FlowValidator — selfie capture config", () => {
+  function selfieCaptureIssues(
+    configure: (s: {
+      allowAgentMode: boolean;
+      enableEnhancedLiveness: boolean;
+    }) => void,
+  ) {
+    const config = new CaptureConfigBuilder();
+    config.captureType = CaptureType.selfie;
+    config.selfie(configure);
+    return runFlowValidation({
+      steps: [{ kind: "capture" as const, config }, processingStep()],
+    });
+  }
+
+  function agentModeIssues(
+    configure: (s: {
+      allowAgentMode: boolean;
+      enableEnhancedLiveness: boolean;
+    }) => void,
+  ): AgentModeWithEnhancedLivenessException[] {
+    return selfieCaptureIssues(configure).filter(
+      (i): i is AgentModeWithEnhancedLivenessException =>
+        i instanceof AgentModeWithEnhancedLivenessException,
+    );
+  }
+
+  const rejectsAgentModePair = (
+    configure: Parameters<typeof agentModeIssues>[0],
+  ): boolean => agentModeIssues(configure).length > 0;
+
+  it("rejects agent mode combined with enhanced liveness", () => {
+    const issues = agentModeIssues((s) => {
+      s.allowAgentMode = true;
+      s.enableEnhancedLiveness = true;
+    });
+    expect(issues).toHaveLength(1);
+    // Wire string partner tooling pivots on — a rename is a breaking change.
+    expect(issues[0]?.errorCode).toBe(
+      "BUILDER_AGENT_MODE_WITH_ENHANCED_LIVENESS",
+    );
+  });
+
+  it("accepts agent mode and enhanced liveness on their own", () => {
+    expect(
+      rejectsAgentModePair((s) => {
+        s.allowAgentMode = true;
+      }),
+    ).toBe(false);
+    expect(
+      rejectsAgentModePair((s) => {
+        s.enableEnhancedLiveness = true;
+      }),
+    ).toBe(false);
+  });
+});
+
 describe("FlowValidator — analyzer-per-capture-type", () => {
   for (const { name, value: jobType } of SELFIE_JOB_TYPES) {
     it(`${name}: missing ml block emits "is required" + MissingMLConfigurationBlockException`, () => {

package/src/presentation/flow/validation/flow_validator.ts

@@ -10,7 +10,11 @@ import type {
   UserDetails,
 } from "../../../core/models/params";
 import { JobType } from "../../../core/models/job_type";
-import type { ScreenSpec } from "../dsl/builder/screens_builder";
+import type {
+  DocumentCaptureConfigBuilder,
+  ScreenSpec,
+  SelfieCaptureConfigBuilder,
+} from "../dsl/builder/screens_builder";
 
 type ConsentScreenStep = Extract<ScreenSpec, { kind: "consent" }>;
 import { IssueSeverity } from "../../../core/exception/issue_severity";
@@ -25,6 +29,7 @@ import {
   MissingNetworkConfigurationBlockException,
 } from "../../../core/exception/job_validation_exceptions";
 import {
+  AgentModeWithEnhancedLivenessException,
   InvalidDocumentCaptureConfigException,
   InvalidMissingCaptureTypeException,
 } from "../../../core/exception/capture_validation_exceptions";
@@ -69,6 +74,51 @@ type FlowValidatorInput = {
   readonly userDetails?: UserDetails | undefined;
 };
 
+/**
+ * Agent mode captures on the rear lens while the head-turn challenge is only
+ * validated for front-camera framing, so the pair is refused rather than
+ * silently dropping one of them.
+ */
+function selfieConfigIssues(
+  config: SelfieCaptureConfigBuilder | undefined,
+): ValidationIssue[] {
+  if (config?.allowAgentMode && config.enableEnhancedLiveness) {
+    return [new AgentModeWithEnhancedLivenessException()];
+  }
+  return [];
+}
+
+/** Surfaces at most one issue: missing block > missing type > bad aspect ratio. */
+function documentConfigIssues(
+  config: DocumentCaptureConfigBuilder | undefined,
+): ValidationIssue[] {
+  if (config === undefined) {
+    return [
+      new InvalidDocumentCaptureConfigException({
+        reason: "document is required when mode is Document",
+      }),
+    ];
+  }
+  if (config.documentType === undefined) {
+    return [
+      new InvalidDocumentCaptureConfigException({
+        reason: "documentType is required for document capture",
+      }),
+    ];
+  }
+  if (
+    config.knownIdAspectRatio !== undefined &&
+    config.knownIdAspectRatio <= 0
+  ) {
+    return [
+      new InvalidDocumentCaptureConfigException({
+        reason: "knownIdAspectRatio must be > 0 if provided",
+      }),
+    ];
+  }
+  return [];
+}
+
 /**
  * Quick triage of the in-progress builder state. Today the only rule
  * surfaced is the empty-screens-block error — `b.screens(...)` must
@@ -113,32 +163,11 @@ export function runFlowValidation(
       if (step.config.captureType === undefined) {
         issues.push(new InvalidMissingCaptureTypeException());
       }
-      // Document captures carry required config: surface at most one issue per
-      // step (missing block > missing type > bad aspect ratio).
+      if (step.config.captureType === CaptureType.selfie) {
+        issues.push(...selfieConfigIssues(step.config.selfieConfig));
+      }
       if (step.config.captureType === CaptureType.document) {
-        const documentConfig = step.config.documentConfig;
-        if (documentConfig === undefined) {
-          issues.push(
-            new InvalidDocumentCaptureConfigException({
-              reason: "document is required when mode is Document",
-            }),
-          );
-        } else if (documentConfig.documentType === undefined) {
-          issues.push(
-            new InvalidDocumentCaptureConfigException({
-              reason: "documentType is required for document capture",
-            }),
-          );
-        } else if (
-          documentConfig.knownIdAspectRatio !== undefined &&
-          documentConfig.knownIdAspectRatio <= 0
-        ) {
-          issues.push(
-            new InvalidDocumentCaptureConfigException({
-              reason: "knownIdAspectRatio must be > 0 if provided",
-            }),
-          );
-        }
+        issues.push(...documentConfigIssues(step.config.documentConfig));
       }
     }
   }