@smileid/usesmileid 12.0.0-beta01 → 12.0.0

package/src/presentation/components/use_smile_id_instructions_hero.tsx

@@ -27,6 +27,9 @@ const DEFAULT_LOOP_MS = 2000;
 // the hero animation's playback speed, so a long hero composition can't slow
 // the fill down to a crawl.
 export const OVAL_PROGRESS_DURATION_MS = 5500;
+// Document hero card: 4:3 frame, corner radius = 40/384 of its width.
+const HERO_CARD_WIDTH_TO_HEIGHT = 384 / 288;
+const HERO_CARD_CORNER_RATIO = 40 / 384;
 
 export type UseSmileIDInstructionsHeroProps = {
   /** Lottie animation rendered inside the (optional) face-oval ring. */
@@ -39,6 +42,8 @@ export type UseSmileIDInstructionsHeroProps = {
    * scheduled (Enhanced Smart Selfie has no single rising-progress gesture).
    */
   readonly showOvalProgress?: boolean;
+  /** Present the animation inside a cream rounded card instead of a face oval (document instructions). */
+  readonly showCardBackground?: boolean;
   readonly theme?: UseSmileIDTheme;
 };
 
@@ -67,6 +72,7 @@ export function UseSmileIDInstructionsHero({
   source,
   showOval = false,
   showOvalProgress = true,
+  showCardBackground = false,
   theme: themeProp,
 }: UseSmileIDInstructionsHeroProps) {
   const themeFromContext = useUseSmileIDTheme();
@@ -134,6 +140,13 @@ export function UseSmileIDInstructionsHero({
   const verticalOffset = animationSize * ANIMATION_VERTICAL_OFFSET_RATIO;
   const hasSize = ovalWidth > 0 && ovalHeight > 0;
 
+  const cardWidth = Math.min(
+    size.width,
+    size.height * HERO_CARD_WIDTH_TO_HEIGHT,
+  );
+  const cardHeight = cardWidth / HERO_CARD_WIDTH_TO_HEIGHT;
+  const cardRadius = cardWidth * HERO_CARD_CORNER_RATIO;
+
   const onLayout = (event: LayoutChangeEvent) => {
     const { width, height } = event.nativeEvent.layout;
     setSize((previous) =>
@@ -164,77 +177,105 @@ export function UseSmileIDInstructionsHero({
       testID="si_instructions_hero"
     >
       {hasSize ? (
-        <>
-          {showOval ? (
-            <>
-              <Svg
-                width={ovalWidth}
-                height={ovalHeight}
-                style={{
-                  position: "absolute",
-                  left: (size.width - ovalWidth) / 2,
-                  top: (size.height - ovalHeight) / 2,
-                }}
-              >
-                <Ellipse {...ellipseProps} stroke={theme.colors.ovalDefault} />
-              </Svg>
-              {/* Green fill revealed by a bottom-anchored view window —
-                  Android never re-resolves animated SVG clipPath contents,
-                  so the clip must happen at the View layer. */}
-              {showOvalProgress ? (
-                <View
-                  pointerEvents="none"
+        showCardBackground ? (
+          <View
+            style={{
+              position: "absolute",
+              left: (size.width - cardWidth) / 2,
+              top: (size.height - cardHeight) / 2,
+              width: cardWidth,
+              height: cardHeight,
+              borderRadius: cardRadius,
+              overflow: "hidden",
+              backgroundColor: theme.colors.instructionCardBackground,
+            }}
+            testID="si_instructions_hero_card"
+          >
+            <AnimatedLottieView
+              source={source}
+              autoPlay={!lottieDrivenByProgress}
+              loop={!lottieDrivenByProgress}
+              {...(lottieDrivenByProgress ? { progress: heroProgress } : {})}
+              resizeMode="contain"
+              style={{ width: cardWidth, height: cardHeight }}
+            />
+          </View>
+        ) : (
+          <>
+            {showOval ? (
+              <>
+                <Svg
+                  width={ovalWidth}
+                  height={ovalHeight}
                   style={{
                     position: "absolute",
                     left: (size.width - ovalWidth) / 2,
                     top: (size.height - ovalHeight) / 2,
-                    width: ovalWidth,
-                    height: ovalHeight,
                   }}
                 >
-                  <Animated.View
+                  <Ellipse
+                    {...ellipseProps}
+                    stroke={theme.colors.ovalDefault}
+                  />
+                </Svg>
+                {/* Green fill revealed by a bottom-anchored view window —
+                  Android never re-resolves animated SVG clipPath contents,
+                  so the clip must happen at the View layer. */}
+                {showOvalProgress ? (
+                  <View
+                    pointerEvents="none"
                     style={{
                       position: "absolute",
-                      left: 0,
-                      right: 0,
-                      bottom: 0,
-                      overflow: "hidden",
-                      height: ovalProgress.interpolate({
-                        inputRange: [0, 1],
-                        outputRange: [0, ovalHeight],
-                      }),
+                      left: (size.width - ovalWidth) / 2,
+                      top: (size.height - ovalHeight) / 2,
+                      width: ovalWidth,
+                      height: ovalHeight,
                     }}
                   >
-                    <Svg
-                      width={ovalWidth}
-                      height={ovalHeight}
-                      style={{ position: "absolute", left: 0, bottom: 0 }}
+                    <Animated.View
+                      style={{
+                        position: "absolute",
+                        left: 0,
+                        right: 0,
+                        bottom: 0,
+                        overflow: "hidden",
+                        height: ovalProgress.interpolate({
+                          inputRange: [0, 1],
+                          outputRange: [0, ovalHeight],
+                        }),
+                      }}
                     >
-                      <Ellipse
-                        {...ellipseProps}
-                        stroke={theme.colors.ovalActive}
-                      />
-                    </Svg>
-                  </Animated.View>
-                </View>
-              ) : null}
-            </>
-          ) : null}
+                      <Svg
+                        width={ovalWidth}
+                        height={ovalHeight}
+                        style={{ position: "absolute", left: 0, bottom: 0 }}
+                      >
+                        <Ellipse
+                          {...ellipseProps}
+                          stroke={theme.colors.ovalActive}
+                        />
+                      </Svg>
+                    </Animated.View>
+                  </View>
+                ) : null}
+              </>
+            ) : null}
 
-          <AnimatedLottieView
-            source={source}
-            autoPlay={!lottieDrivenByProgress}
-            loop={!lottieDrivenByProgress}
-            {...(lottieDrivenByProgress ? { progress: heroProgress } : {})}
-            style={{
-              position: "absolute",
-              width: animationSize,
-              height: animationSize,
-              left: (size.width - animationSize) / 2,
-              top: (size.height - animationSize) / 2 + verticalOffset,
-            }}
-          />
-        </>
+            <AnimatedLottieView
+              source={source}
+              autoPlay={!lottieDrivenByProgress}
+              loop={!lottieDrivenByProgress}
+              {...(lottieDrivenByProgress ? { progress: heroProgress } : {})}
+              style={{
+                position: "absolute",
+                width: animationSize,
+                height: animationSize,
+                left: (size.width - animationSize) / 2,
+                top: (size.height - animationSize) / 2 + verticalOffset,
+              }}
+            />
+          </>
+        )
       ) : null}
     </View>
   );

package/src/presentation/components/use_smile_id_oval_border_palette.ts

@@ -48,13 +48,17 @@ export const UseSmileIDOvalBorderPalette = {
       case UseSmileIDOverlayState.MULTIPLE_FACES:
         return "ovalWarning";
 
-      // Document states render via UseSmileIDDocumentOverlay, not here.
+      // Document states (UseSmileIDDocumentOverlay resolves its border through
+      // this same table): green once the document is correctly framed, red
+      // while it is detected but mispositioned (too far / close / off-centre /
+      // not steady).
+      case UseSmileIDOverlayState.DOCUMENT_READY:
+        return "ovalActive";
       case UseSmileIDOverlayState.DOCUMENT_NOT_CENTERED:
       case UseSmileIDOverlayState.DOCUMENT_TOO_FAR:
       case UseSmileIDOverlayState.DOCUMENT_TOO_CLOSE:
       case UseSmileIDOverlayState.DOCUMENT_HOLD_STILL:
-      case UseSmileIDOverlayState.DOCUMENT_READY:
-        return "ovalDefault";
+        return "ovalWarning";
     }
   },
 } as const;

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

@@ -3,6 +3,7 @@ import { DocumentSide } from "@smileid/usesmileid_bridge";
 import { FlowNavigationManager } from "../flow_navigation_manager";
 import {
   CaptureType,
+  type DocumentCaptureConfigBuilder,
   ScreensBuilder,
   type ScreensConfig,
 } from "../dsl/builder/screens_builder";
@@ -40,7 +41,7 @@ function twoSidedDocumentFlow(): ScreensConfig {
     screens.capture((capture) => {
       capture.captureType = CaptureType.document;
       capture.document((document) => {
-        document.documentType = DocumentType.SouthAfricaGreenBook; // hasBackSide
+        document.documentType = DocumentType.GenericDocument(); // hasBackSide
         document.captureBothSides = true;
         document.allowSkipBack = true;
       });
@@ -136,6 +137,44 @@ describe("FlowNavigationManager — document per-side preview loop", () => {
     );
   });
 
+  it("with no document preview, still routes to the BACK capture after the front", () => {
+    // Regression: captureBothSides must capture the back even with no document
+    // preview { }, not jump straight to the selfie.
+    const noPreviewFlow = buildScreens((screens) => {
+      screens.instructions();
+      screens.capture((capture) => {
+        capture.captureType = CaptureType.document;
+        capture.document((document) => {
+          document.documentType = DocumentType.GenericDocument(); // hasBackSide
+          document.captureBothSides = true;
+          document.allowSkipBack = false;
+        });
+      });
+      screens.capture((capture) => {
+        capture.captureType = CaptureType.selfie;
+      });
+      screens.processing();
+    });
+    const manager = makeManager(noPreviewFlow);
+    manager.navigateToNext(); // instructions → document capture (front)
+    manager.setCapturedFrontDocument("file:///front.jpg");
+
+    // No preview follows → re-enter the document capture for the back side.
+    const next = manager.getNextScreen();
+    expect(next?.kind).toBe("capture");
+    expect(next?.kind === "capture" ? next.config.captureType : undefined).toBe(
+      CaptureType.document,
+    );
+
+    // After the back is captured, advance to the selfie.
+    manager.navigateToNext(); // → document capture (back)
+    manager.setCapturedBackDocument("file:///back.jpg");
+    const afterBack = manager.getNextScreen();
+    expect(
+      afterBack?.kind === "capture" ? afterBack.config.captureType : undefined,
+    ).toBe(CaptureType.selfie);
+  });
+
   it("retakeCurrentDocumentSide clears the back first, then the front", () => {
     const manager = makeManager(twoSidedDocumentFlow());
     manager.setCapturedFrontDocument("file:///front.jpg");
@@ -282,4 +321,164 @@ describe("FlowNavigationManager — document image origin metadata", () => {
       entries.some((entry) => entry.name === "DocumentBackImageOrigin"),
     ).toBe(false);
   });
+
+  it("stamps capture telemetry and image properties onto the submitted metadata", () => {
+    const repository = new StubRepository();
+    const manager = makeManager(
+      buildScreens((screens) => screens.processing()),
+      {
+        documentVerificationParams: { country: "NG" },
+        userDetails: SAMPLE_USER_DETAILS,
+        network: {
+          config: {
+            jobType: JobType.documentVerification,
+            token: "k",
+            partnerConfig: {
+              partnerId: "p",
+              callbackUrl: "",
+              useSandbox: true,
+            },
+          },
+        },
+      },
+      repository,
+    );
+    manager.setCapturedSelfie("file:///selfie.jpg", ["file:///l1.jpg"]);
+    manager.setCapturedFrontDocument("file:///front.jpg");
+    manager.recordSelfieCaptureTelemetry({
+      durationMs: 4200,
+      retries: 0,
+      cameraName: "com.apple.avfoundation:front",
+      devicePositions: ["1000,0.1,0.2,0.98", "1066,0.1,0.3,0.97"],
+      deviceMovementDetected: 0.35,
+    });
+    manager.recordDocumentCaptureTelemetry(DocumentSide.Front, {
+      durationMs: 5000,
+      retries: 1,
+      devicePositions: [],
+      deviceMovementDetected: null,
+    });
+    manager.setConsent(consentInfo);
+
+    manager.beginSubmissionIfNeeded();
+
+    const entries = repository.received[0]!.metadata.toEntries();
+    // Selfie: duration + retries (0 kept) + image color depth / pixel config.
+    expect(entries).toContainEqual({
+      name: "selfie_capture_duration_ms",
+      value: "4200",
+    });
+    expect(entries).toContainEqual({
+      name: "selfie_capture_retries",
+      value: "0",
+    });
+    expect(entries).toContainEqual({
+      name: "selfie_image_color_depth",
+      value: "24",
+    });
+    expect(entries).toContainEqual({
+      name: "selfie_image_pixel_config",
+      value: "RGB_888",
+    });
+    // Document front: telemetry + image color depth / pixel config. (Original/final compressed
+    // sizes are stamped in the repository around the compression pass, not by the flow manager.)
+    expect(entries).toContainEqual({
+      name: "document_front_capture_duration_ms",
+      value: "5000",
+    });
+    expect(entries).toContainEqual({
+      name: "document_front_capture_retries",
+      value: "1",
+    });
+    // Back side never captured → no back entries.
+    expect(
+      entries.some((entry) => entry.name === "document_back_capture_retries"),
+    ).toBe(false);
+    // Camera id from the telemetry.
+    expect(entries).toContainEqual({
+      name: "camera_name",
+      value: "com.apple.avfoundation:front",
+    });
+    // Accelerometer telemetry from the selfie capture.
+    expect(entries).toContainEqual({
+      name: "device_positions",
+      value: JSON.stringify(["1000,0.1,0.2,0.98", "1066,0.1,0.3,0.97"]),
+    });
+    expect(entries).toContainEqual({
+      name: "device_movement_detected",
+      value: "0.35",
+    });
+  });
+});
+
+describe("FlowNavigationManager — documentFrameAspectRatio", () => {
+  function documentFlow(
+    configure: (document: DocumentCaptureConfigBuilder) => void,
+  ): ScreensConfig {
+    return buildScreens((screens) => {
+      screens.capture((capture) => {
+        capture.captureType = CaptureType.document;
+        capture.document(configure);
+      });
+    });
+  }
+
+  it("uses the document type's own knownAspectRatio for presets", () => {
+    expect(
+      makeManager(
+        documentFlow((document) => {
+          document.documentType = DocumentType.Passport;
+        }),
+      ).documentFrameAspectRatio,
+    ).toBeCloseTo(356 / 272);
+
+    expect(
+      makeManager(
+        documentFlow((document) => {
+          document.documentType = DocumentType.SouthAfricaGreenBook;
+        }),
+      ).documentFrameAspectRatio,
+    ).toBeCloseTo(320 / 428);
+  });
+
+  it("falls back to the partner ratio, then the orientation default", () => {
+    // Generic landscape with no fixed ratio → landscape default.
+    expect(
+      makeManager(
+        documentFlow((document) => {
+          document.documentType = DocumentType.GenericDocument();
+        }),
+      ).documentFrameAspectRatio,
+    ).toBeCloseTo(1.586);
+
+    // A partner override wins when the type has no fixed ratio.
+    expect(
+      makeManager(
+        documentFlow((document) => {
+          document.documentType = DocumentType.GenericDocument();
+          document.knownIdAspectRatio = 1.4;
+        }),
+      ).documentFrameAspectRatio,
+    ).toBeCloseTo(1.4);
+
+    // Generic portrait with no fixed ratio → portrait default.
+    expect(
+      makeManager(
+        documentFlow((document) => {
+          document.documentType = DocumentType.GenericDocument({
+            orientation: "Portrait",
+          });
+        }),
+      ).documentFrameAspectRatio,
+    ).toBeCloseTo(0.65);
+  });
+
+  it("is undefined when the flow has no document capture step", () => {
+    const selfieFlow = buildScreens((screens) => {
+      screens.capture((capture) => {
+        capture.captureType = CaptureType.selfie;
+      });
+    });
+    expect(makeManager(selfieFlow).documentFrameAspectRatio).toBeUndefined();
+  });
 });

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

@@ -8,8 +8,22 @@ import type { ConfigOptions } from "../../../../core/models/config";
  * populated.
  */
 export class UseSmileIDConfigBuilder {
+  /**
+   * When true (the default), the SDK reports its own crashes to Smile ID's
+   * crash-reporting backend. Set false to opt out.
+   */
   enableCrashReporting = true;
+
+  /**
+   * When true, enables verbose SDK debug logging and on-device
+   * diagnostics. Defaults to false; leave off in production.
+   */
   enableDebugMode = false;
+
+  /**
+   * When true, captured images are written to disk so the job can be
+   * submitted later when connectivity returns. Defaults to false.
+   */
   allowOfflineMode = false;
 
   build(): ConfigOptions {

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

@@ -34,7 +34,7 @@ import {
  */
 
 export class FaceAnalyzerScope {
-  /** Register the face analyzer for this scope. */
+  /** Registers a detection backend for this capture type. */
   add(analyzer: FaceAnalyzer): void {
     this._analyzer = analyzer;
   }
@@ -130,7 +130,7 @@ export class FaceAnalyzerScope {
 }
 
 export class DocumentAnalyzerScope {
-  /** Register the document analyzer for this scope. */
+  /** Registers a detection backend for this capture type. */
   add(analyzer: DocumentAnalyzer): void {
     this._analyzer = analyzer;
   }
@@ -143,12 +143,20 @@ export class AnalyzerRegistryBuilder {
   private _selfieConfig?: FaceConfig | undefined;
   private _document?: DocumentAnalyzer | undefined;
 
-  /** Open a selfie-analyzer registration scope. */
+  /**
+   * Registers and tunes the analyzer(s) for the selfie capture type.
+   * Calling it again for the same capture type replaces the previous
+   * registration.
+   */
   forCaptureType(
     captureType: CaptureType.selfie,
     block: (a: FaceAnalyzerScope) => void,
   ): void;
-  /** Open a document-analyzer registration scope. */
+  /**
+   * Registers and tunes the analyzer(s) for the document capture type.
+   * Calling it again for the same capture type replaces the previous
+   * registration.
+   */
   forCaptureType(
     captureType: CaptureType.document,
     block: (a: DocumentAnalyzerScope) => void,
@@ -188,6 +196,7 @@ export class AnalyzerRegistryBuilder {
 export class UseSmileIDMLBuilder {
   private _analyzers?: AnalyzerRegistryBuilder;
 
+  /** Registers the ML analyzers for the flow, keyed by capture type. */
   analyzers(block: (a: AnalyzerRegistryBuilder) => void): void {
     if (!this._analyzers) this._analyzers = new AnalyzerRegistryBuilder();
     block(this._analyzers);