@smileid/usesmileid 12.0.0-beta01 → 12.0.0

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

@@ -11,7 +11,6 @@ import {
   ENHANCED_SMART_SELFIE_ANIMATION_SIZE,
 } from "../use_smile_id_enhanced_smart_selfie_clip";
 import {
-  ENHANCED_SMART_SELFIE_ANIMATION_OPACITY,
   ENHANCED_SMART_SELFIE_ANIMATION_SPEED,
   ENHANCED_SMART_SELFIE_TOTAL_FRAMES,
 } from "../helpers/enhanced_smart_selfie_animation_frames";
@@ -216,7 +215,7 @@ describe("UseSmileIDEnhancedSmartSelfieClip", () => {
   });
 
   describe("tuning — opacity + speed", () => {
-    it("renders the cue at 0.75 opacity so the face stays the focal point", async () => {
+    it("renders the cue at full opacity (no translucency over the animation)", async () => {
       const tree = renderClip({ pingPong: false });
       await act(async () => {
         await Promise.resolve();
@@ -227,8 +226,8 @@ describe("UseSmileIDEnhancedSmartSelfieClip", () => {
           match.props.style !== undefined && match.props.style !== null,
       );
       expect(container).toBeDefined();
-      const style = container!.props.style as { opacity: number };
-      expect(style.opacity).toBe(ENHANCED_SMART_SELFIE_ANIMATION_OPACITY);
+      const style = container!.props.style as { opacity?: number };
+      expect(style.opacity).toBeUndefined();
     });
 
     it("plays the full primer at 0.6x speed", async () => {

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

@@ -7,7 +7,10 @@ import {
 } from "react-test-renderer";
 import { Text } from "react-native";
 import { UseSmileIDGuidelineThumbnail } from "../use_smile_id_guideline_thumbnail";
-import { SELFIE_GUIDELINES } from "../../flow/model/instructions_defaults";
+import {
+  DOCUMENT_GUIDELINES_PASSPORT,
+  SELFIE_GUIDELINES,
+} from "../../flow/model/instructions_defaults";
 
 function render(element: React.ReactElement) {
   let tree!: ReturnType<typeof createRenderer>;
@@ -77,3 +80,33 @@ describe("UseSmileIDGuidelineThumbnail", () => {
     );
   });
 });
+
+// DOCUMENT_GUIDELINES_PASSPORT order: [Good (allowed), …, Not reflective]; these
+// carry a `card` size → the thumbnail renders the document-card layout.
+const documentAllowedGuideline = DOCUMENT_GUIDELINES_PASSPORT[0]!;
+const documentBlockedGuideline = DOCUMENT_GUIDELINES_PASSPORT[3]!;
+
+describe("UseSmileIDGuidelineThumbnail — document card", () => {
+  it("renders the caption and allowed badge for a document guideline", () => {
+    const { root } = render(
+      <UseSmileIDGuidelineThumbnail guideline={documentAllowedGuideline} />,
+    );
+    expect(findTextNode(root, "Good")).not.toBeNull();
+    expect(
+      root.findAllByProps({ accessibilityLabel: "Allowed" })[0],
+    ).toBeTruthy();
+    expect(
+      root.findAllByProps({ accessibilityLabel: "Not allowed" }),
+    ).toHaveLength(0);
+  });
+
+  it("renders the blocked badge and caption for a blocked document guideline", () => {
+    const { root } = render(
+      <UseSmileIDGuidelineThumbnail guideline={documentBlockedGuideline} />,
+    );
+    expect(findTextNode(root, "Not reflective")).not.toBeNull();
+    expect(
+      root.findAllByProps({ accessibilityLabel: "Not allowed" })[0],
+    ).toBeTruthy();
+  });
+});

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

@@ -7,6 +7,7 @@ import {
   OVAL_PROGRESS_DURATION_MS,
   loopDurationMs,
 } from "../use_smile_id_instructions_hero";
+import { AnimatedLottieView } from "../helpers/animated_lottie_view";
 import { SELFIE_HERO_ANIMATION } from "../../flow/model/instructions_defaults";
 
 function render(element: React.ReactElement) {
@@ -76,4 +77,30 @@ describe("UseSmileIDInstructionsHero", () => {
       timingSpy.mockRestore();
     }
   });
+
+  it("gives the document card hero explicit dimensions (no intrinsic-size flash)", () => {
+    const tree = render(
+      <UseSmileIDInstructionsHero
+        source={SELFIE_HERO_ANIMATION}
+        showCardBackground
+        showOvalProgress={false}
+      />,
+    );
+    // The renderer doesn't fire onLayout on its own; drive it so the measured
+    // subtree (card + Lottie) materializes.
+    const hero = tree.root.findByProps({ testID: "si_instructions_hero" });
+    act(() => {
+      hero.props.onLayout({
+        nativeEvent: { layout: { width: 384, height: 600 } },
+      });
+    });
+
+    const lottie = tree.root.findByType(AnimatedLottieView);
+    const style = lottie.props.style as { width?: unknown; height?: unknown };
+    // Regression guard: explicit numeric width/height (not absoluteFill), else the Lottie
+    // flashes at the composition's intrinsic size on first render.
+    expect(typeof style.width).toBe("number");
+    expect(typeof style.height).toBe("number");
+    act(() => tree.unmount());
+  });
 });

package/src/presentation/components/__tests__/use_smile_id_oval_border_palette.test.ts

@@ -16,17 +16,14 @@ describe("UseSmileIDOvalBorderPalette", () => {
     UseSmileIDOverlayState.MOVE_RIGHT,
     UseSmileIDOverlayState.MOVE_UP,
     UseSmileIDOverlayState.MOVE_DOWN,
-    UseSmileIDOverlayState.DOCUMENT_NOT_CENTERED,
-    UseSmileIDOverlayState.DOCUMENT_TOO_FAR,
-    UseSmileIDOverlayState.DOCUMENT_TOO_CLOSE,
-    UseSmileIDOverlayState.DOCUMENT_HOLD_STILL,
-    UseSmileIDOverlayState.DOCUMENT_READY,
   ];
 
   const active: UseSmileIDOverlayState[] = [
     UseSmileIDOverlayState.READY,
     UseSmileIDOverlayState.CAPTURING,
     UseSmileIDOverlayState.PROCESSING,
+    // Document is correctly framed → green, mirroring the selfie ready state.
+    UseSmileIDOverlayState.DOCUMENT_READY,
   ];
 
   const warning: UseSmileIDOverlayState[] = [
@@ -38,6 +35,11 @@ describe("UseSmileIDOvalBorderPalette", () => {
     UseSmileIDOverlayState.WRONG_ORIENTATION,
     UseSmileIDOverlayState.NOT_SMILING,
     UseSmileIDOverlayState.MULTIPLE_FACES,
+    // Document detected but mispositioned → red, mirroring the face warnings.
+    UseSmileIDOverlayState.DOCUMENT_NOT_CENTERED,
+    UseSmileIDOverlayState.DOCUMENT_TOO_FAR,
+    UseSmileIDOverlayState.DOCUMENT_TOO_CLOSE,
+    UseSmileIDOverlayState.DOCUMENT_HOLD_STILL,
   ];
 
   it("covers every overlay state exactly once across the three buckets", () => {

package/src/presentation/components/helpers/enhanced_smart_selfie_animation_frames.ts

@@ -50,12 +50,6 @@ export const ENHANCED_SMART_SELFIE_FRAME_RATE = 30;
  */
 export const ENHANCED_SMART_SELFIE_ANIMATION_SPEED = 0.6;
 
-/**
- * Opacity for the ESS cues so the face stays the focal point behind the
- * translucent arrow overlay.
- */
-export const ENHANCED_SMART_SELFIE_ANIMATION_OPACITY = 0.75;
-
 /**
  * Resolve the keyframe span for [direction] — the green `matched` span
  * while [poseMatched], otherwise the grey `pending` span. Pure, so the

package/src/presentation/components/icons/index.tsx

@@ -4,10 +4,18 @@ import {
   SI_FILLED_CHECK_CIRCLE,
   SI_FILLED_CLOSE_CIRCLE,
   SI_GUIDELINE_ACCESSORIES,
-  SI_GUIDELINE_DOCUMENT_GOOD,
-  SI_GUIDELINE_DOCUMENT_NOT_BLURRY,
-  SI_GUIDELINE_DOCUMENT_NOT_CROPPED,
-  SI_GUIDELINE_DOCUMENT_NOT_REFLECTIVE,
+  SI_GUIDELINE_DOCUMENT_GENERIC_GOOD,
+  SI_GUIDELINE_DOCUMENT_GENERIC_NOT_BLURRY,
+  SI_GUIDELINE_DOCUMENT_GENERIC_NOT_CROPPED,
+  SI_GUIDELINE_DOCUMENT_GENERIC_NOT_REFLECTIVE,
+  SI_GUIDELINE_DOCUMENT_GREEN_BOOK_GOOD,
+  SI_GUIDELINE_DOCUMENT_GREEN_BOOK_NOT_BLURRY,
+  SI_GUIDELINE_DOCUMENT_GREEN_BOOK_NOT_CROPPED,
+  SI_GUIDELINE_DOCUMENT_GREEN_BOOK_NOT_REFLECTIVE,
+  SI_GUIDELINE_DOCUMENT_PASSPORT_GOOD,
+  SI_GUIDELINE_DOCUMENT_PASSPORT_NOT_BLURRY,
+  SI_GUIDELINE_DOCUMENT_PASSPORT_NOT_CROPPED,
+  SI_GUIDELINE_DOCUMENT_PASSPORT_NOT_REFLECTIVE,
   SI_GUIDELINE_GOOD,
   SI_GUIDELINE_MULTIPLE_FACES,
   SI_GUIDELINE_POOR_LIGHTING,
@@ -245,23 +253,62 @@ export const SiGuidelinePoorLighting = guidelineIllustration(
   SI_GUIDELINE_POOR_LIGHTING,
 );
 
-// Document-capture guideline illustrations. All four render the shared ID-card
-// placeholder for now; per-guideline assets are pending design.
-/** "Good" document-guideline illustration (allowed). */
-export const SiGuidelineDocumentGood = guidelineIllustration(
-  SI_GUIDELINE_DOCUMENT_GOOD,
+// Document-capture guideline illustrations — self-contained card art per
+// document type (see `instruction_svg_strings`). Each renders at the asset's
+// natural viewBox; `UseSmileIDGuidelineThumbnail` sizes and frames them.
+
+// --- Generic document (landscape) ---
+/** "Good" generic-document guideline illustration (allowed). */
+export const SiGuidelineDocumentGenericGood = guidelineIllustration(
+  SI_GUIDELINE_DOCUMENT_GENERIC_GOOD,
+);
+/** "Not cropped" generic-document guideline illustration (blocked). */
+export const SiGuidelineDocumentGenericNotCropped = guidelineIllustration(
+  SI_GUIDELINE_DOCUMENT_GENERIC_NOT_CROPPED,
+);
+/** "Not blurry" generic-document guideline illustration (blocked). */
+export const SiGuidelineDocumentGenericNotBlurry = guidelineIllustration(
+  SI_GUIDELINE_DOCUMENT_GENERIC_NOT_BLURRY,
+);
+/** "Not reflective" generic-document guideline illustration (blocked). */
+export const SiGuidelineDocumentGenericNotReflective = guidelineIllustration(
+  SI_GUIDELINE_DOCUMENT_GENERIC_NOT_REFLECTIVE,
+);
+
+// --- Passport (landscape) ---
+/** "Good" passport guideline illustration (allowed). */
+export const SiGuidelineDocumentPassportGood = guidelineIllustration(
+  SI_GUIDELINE_DOCUMENT_PASSPORT_GOOD,
+);
+/** "Not cropped" passport guideline illustration (blocked). */
+export const SiGuidelineDocumentPassportNotCropped = guidelineIllustration(
+  SI_GUIDELINE_DOCUMENT_PASSPORT_NOT_CROPPED,
+);
+/** "Not blurry" passport guideline illustration (blocked). */
+export const SiGuidelineDocumentPassportNotBlurry = guidelineIllustration(
+  SI_GUIDELINE_DOCUMENT_PASSPORT_NOT_BLURRY,
+);
+/** "Not reflective" passport guideline illustration (blocked). */
+export const SiGuidelineDocumentPassportNotReflective = guidelineIllustration(
+  SI_GUIDELINE_DOCUMENT_PASSPORT_NOT_REFLECTIVE,
+);
+
+// --- South Africa green book (portrait) ---
+/** "Good" green-book guideline illustration (allowed). */
+export const SiGuidelineDocumentGreenBookGood = guidelineIllustration(
+  SI_GUIDELINE_DOCUMENT_GREEN_BOOK_GOOD,
 );
-/** "Not cropped" document-guideline illustration (blocked). */
-export const SiGuidelineDocumentNotCropped = guidelineIllustration(
-  SI_GUIDELINE_DOCUMENT_NOT_CROPPED,
+/** "Not cropped" green-book guideline illustration (blocked). */
+export const SiGuidelineDocumentGreenBookNotCropped = guidelineIllustration(
+  SI_GUIDELINE_DOCUMENT_GREEN_BOOK_NOT_CROPPED,
 );
-/** "Not blurry" document-guideline illustration (blocked). */
-export const SiGuidelineDocumentNotBlurry = guidelineIllustration(
-  SI_GUIDELINE_DOCUMENT_NOT_BLURRY,
+/** "Not blurry" green-book guideline illustration (blocked). */
+export const SiGuidelineDocumentGreenBookNotBlurry = guidelineIllustration(
+  SI_GUIDELINE_DOCUMENT_GREEN_BOOK_NOT_BLURRY,
 );
-/** "Not reflective" document-guideline illustration (blocked). */
-export const SiGuidelineDocumentNotReflective = guidelineIllustration(
-  SI_GUIDELINE_DOCUMENT_NOT_REFLECTIVE,
+/** "Not reflective" green-book guideline illustration (blocked). */
+export const SiGuidelineDocumentGreenBookNotReflective = guidelineIllustration(
+  SI_GUIDELINE_DOCUMENT_GREEN_BOOK_NOT_REFLECTIVE,
 );
 
 /** Capture-guidelines section-header glyph; tint via `color` (currentColor). */

package/src/presentation/components/use_smile_id_attribution.tsx

@@ -8,7 +8,7 @@ export type UseSmileIDAttributionProps = {
   /**
    * Force the light-tone attribution regardless of the active
    * colour scheme. Used by surfaces that always render light
-   * (capture screen overlay, processing screen card).
+   * (the capture screen overlay).
    */
   readonly forceLightMode?: boolean;
   readonly testID?: string;

package/src/presentation/components/use_smile_id_button.tsx

@@ -23,8 +23,8 @@ export type UseSmileIDButtonProps = {
  * Pill-shaped primary / secondary button (48-dp height, 32-radius
  * corners).
  *
- * Secondary variant: transparent background + 1-pt stroke in the
- * secondary colour + primary-coloured label.
+ * Secondary variant: transparent background + 2-pt stroke in the
+ * primary colour + primary-coloured label.
  */
 export function UseSmileIDButton(props: UseSmileIDButtonProps) {
   const themeFromContext = useUseSmileIDTheme();
@@ -58,8 +58,8 @@ export function UseSmileIDButton(props: UseSmileIDButtonProps) {
               ? "transparent"
               : theme.colors.primary,
           borderColor:
-            !disabled && isSecondary ? theme.colors.secondary : "transparent",
-          borderWidth: !disabled && isSecondary ? 1 : 0,
+            !disabled && isSecondary ? theme.colors.primary : "transparent",
+          borderWidth: !disabled && isSecondary ? 2 : 0,
           opacity: disabled ? 1 : pressed ? 0.85 : 1,
         },
       ]}

package/src/presentation/components/use_smile_id_capture_content.tsx

@@ -9,6 +9,7 @@ import {
 import { SafeAreaView } from "react-native-safe-area-context";
 import type { ScanHeadTurnDirection } from "@smileid/usesmileid_bridge";
 import { CaptureType } from "../../core/models/ml_config";
+import type { DocumentType } from "../../core/models/document_type";
 import { defaultLightTheme, type UseSmileIDTheme } from "../theme/theme";
 import { useUseSmileIDTheme } from "../theme/theme_context";
 import {
@@ -45,6 +46,10 @@ export type UseSmileIDCaptureContentState = {
   /** Show the Start Capture control (pre-flight instruction state only). */
   readonly showCaptureButton: boolean;
   readonly knownIdAspectRatio?: number;
+  /** Document type — selects the in-frame shimmer skeleton. Ignored for selfie. */
+  readonly documentTypeKind?: DocumentType["kind"];
+  /** Active side is the back — swaps the generic shimmer front→back. Ignored for selfie. */
+  readonly isBackSide?: boolean;
   /** Document manual shutter availability (capture-mode + fallback-timer driven). Ignored for selfie. */
   readonly showManualShutter?: boolean;
   /** Document gallery-upload availability (`allowGalleryUpload`). Ignored for selfie. */
@@ -72,6 +77,13 @@ export type UseSmileIDCaptureContentProps = {
   readonly onGalleryUpload?: (() => void) | undefined;
   /** Disables document controls while a manual/gallery delivery is in flight. */
   readonly documentControlsEnabled?: boolean | undefined;
+  /**
+   * Reports the camera-viewport (canvas) size on layout so the screen can
+   * derive the document crop region from the same geometry the overlay draws.
+   */
+  readonly onViewportLayout?:
+    | ((size: { width: number; height: number }) => void)
+    | undefined;
   readonly theme?: UseSmileIDTheme | undefined;
 };
 
@@ -96,9 +108,14 @@ function UseSmileIDCaptureContentInner(props: UseSmileIDCaptureContentProps) {
         ? previous
         : { width, height },
     );
+    // Surface the viewport size; the screen dedupes no-change passes.
+    props.onViewportLayout?.({ width, height });
   };
 
   const isSelfie = state.captureType === CaptureType.selfie;
+  // Landscape document moves the close ✕ into the control lane; portrait /
+  // selfie keep it in the top bar. False until the canvas is measured.
+  const isLandscapeDocument = !isSelfie && canvas.width > canvas.height;
   const feedback = state.feedbackKey
     ? resolveFeedbackCopy(state.feedbackKey, loc)
     : null;
@@ -129,6 +146,10 @@ function UseSmileIDCaptureContentInner(props: UseSmileIDCaptureContentProps) {
               containerWidth={canvas.width}
               containerHeight={canvas.height}
               theme={theme}
+              isBackSide={state.isBackSide ?? false}
+              {...(state.documentTypeKind !== undefined
+                ? { documentTypeKind: state.documentTypeKind }
+                : {})}
               {...(state.knownIdAspectRatio !== undefined
                 ? { knownIdAspectRatio: state.knownIdAspectRatio }
                 : {})}
@@ -159,11 +180,11 @@ function UseSmileIDCaptureContentInner(props: UseSmileIDCaptureContentProps) {
               />
             ) : null
           ) : null}
-          {/* Document control slot: shutter + gallery while positioning;
-              progress spinner once capture commits (they never coexist). */}
+          {/* Document control slot: shutter + gallery while positioning (plus the
+              close ✕ in landscape). The capture-progress spinner renders in the
+              overlay only while capturing, so it never coexists with these controls. */}
           {!isSelfie ? (
             <UseSmileIDDocumentCaptureControls
-              capturing={isDocumentCaptureActive(state.overlayState)}
               showManualShutter={
                 (state.showManualShutter ?? false) &&
                 props.onManualShutter !== undefined &&
@@ -180,14 +201,17 @@ function UseSmileIDCaptureContentInner(props: UseSmileIDCaptureContentProps) {
               onGallery={props.onGalleryUpload ?? noop}
               shutterAccessibilityLabel={loc.siCdDocumentCaptureShutter}
               galleryAccessibilityLabel={loc.siCdDocumentGallery}
+              closeAccessibilityLabel={loc.siCdClose}
+              onClose={props.onClose}
             />
           ) : null}
         </>
       ) : null}
 
-      {/* Camera stays full-bleed; only the control layers inset from the system bars. */}
+      {/* Control layers inset from the system bars (camera stays full-bleed);
+          both horizontal edges so landscape keeps chrome clear of the notch. */}
       <SafeAreaView
-        edges={["top"]}
+        edges={["top", "left", "right"]}
         style={[
           styles.topBar,
           {
@@ -207,8 +231,9 @@ function UseSmileIDCaptureContentInner(props: UseSmileIDCaptureContentProps) {
         ) : (
           <View style={styles.chromeSpacer} />
         )}
-        {/* Close/cancel (document chrome) — top-right, mirrors the back button. */}
-        {props.onClose ? (
+        {/* Close/cancel (document chrome) — top-right in portrait / selfie; in
+            landscape document capture the ✕ moves into the control lane. */}
+        {props.onClose && !isLandscapeDocument ? (
           <Pressable
             onPress={props.onClose}
             accessibilityRole="button"
@@ -247,10 +272,9 @@ function UseSmileIDCaptureContentInner(props: UseSmileIDCaptureContentProps) {
           <Text
             style={{
               ...theme.typography.cardTitle,
-              // Light-palette forced: overlay is locked to light mode (selfie navy-on-white).
-              color: isSelfie
-                ? defaultLightTheme.colors.primary
-                : defaultLightTheme.colors.captureFeedbackText,
+              // The capture screen supplies the light-resolved partner theme, so
+              // this stays light-on-light while honouring a partner `primary`.
+              color: theme.colors.primary,
               textAlign: "center",
             }}
             testID="si_capture_feedback_text"
@@ -261,7 +285,7 @@ function UseSmileIDCaptureContentInner(props: UseSmileIDCaptureContentProps) {
       ) : null}
 
       <SafeAreaView
-        edges={["bottom"]}
+        edges={["bottom", "left", "right"]}
         style={[
           styles.bottom,
           {

package/src/presentation/components/use_smile_id_captured_document_image.tsx

@@ -1,17 +1,13 @@
 import type { ReactNode } from "react";
 import { Image, StyleSheet, View } from "react-native";
-import {
-  defaultFrameAspectRatio,
-  type DocumentOrientation,
-} from "../../core/models/document_type";
 import type { UseSmileIDTheme } from "../theme/theme";
 import { useUseSmileIDTheme } from "../theme/theme_context";
 
 export type UseSmileIDCapturedDocumentImageProps = {
   /** Local file URI (`file:///…`) of the captured document side. */
   readonly uri?: string;
-  /** Drives the frame aspect: landscape fills width, portrait fills height. */
-  readonly orientation: DocumentOrientation;
+  /** Capture-frame aspect ratio (width / height): ≥1 fills width (landscape), <1 fills height (portrait). */
+  readonly aspectRatio: number;
   /** Content centered over the document rect — e.g. the processing-screen status badge. */
   readonly overlayChild?: ReactNode;
   /** Accessible name for the image; when unset the image stays decorative. */
@@ -33,8 +29,7 @@ export function UseSmileIDCapturedDocumentImage(
 ) {
   const themeFromContext = useUseSmileIDTheme();
   const theme = props.theme ?? themeFromContext;
-  const aspectRatio = defaultFrameAspectRatio(props.orientation);
-  // Landscape (aspect ≥ 1) is width-bound; portrait is height-bound.
+  const aspectRatio = props.aspectRatio;
   const fill = aspectRatio >= 1 ? styles.fillWidth : styles.fillHeight;
 
   return (

package/src/presentation/components/use_smile_id_document_capture_controls.tsx

@@ -1,7 +1,7 @@
 import { Pressable, StyleSheet, View } from "react-native";
+import { SafeAreaView } from "react-native-safe-area-context";
 import { defaultLightTheme } from "../theme/theme";
-import { SiGallery } from "./icons";
-import { UseSmileIDCaptureSpinner } from "./use_smile_id_capture_spinner";
+import { SiGallery, SiOutlineClose } from "./icons";
 
 export type UseSmileIDDocumentCaptureControlsProps = {
   /** Manual shutter — taps capture a still through the document pipeline. */
@@ -9,30 +9,43 @@ export type UseSmileIDDocumentCaptureControlsProps = {
   /** Gallery upload — taps open the photo library to import a document. */
   readonly showGallery: boolean;
   /**
-   * Landscape: controls form a trailing-edge column; portrait: a bottom row.
-   * Driven by the measured canvas aspect (not the lock) so it follows what renders.
+   * Landscape → trailing-edge lane (✕ top, controls centred); portrait →
+   * centred bottom row (✕ in the top chrome). From the measured canvas aspect.
    */
   readonly isLandscape: boolean;
   /** Disables presses (e.g. a delivery is already in flight). */
   readonly enabled: boolean;
-  /** Capture is committing — the slot shows the progress spinner instead of shutter/gallery. */
-  readonly capturing: boolean;
+  /**
+   * Close/cancel the whole flow. Rendered at the top of the landscape lane so it
+   * shares the shutter's centre-x; in portrait the top chrome renders it instead.
+   */
+  readonly onClose?: (() => void) | undefined;
   readonly onManualShutter: () => void;
   readonly onGallery: () => void;
   /** Localized screen-reader label for the shutter (`si_cd_document_capture_shutter`). */
   readonly shutterAccessibilityLabel: string;
   /** Localized screen-reader label for the gallery button (`si_cd_document_gallery`). */
   readonly galleryAccessibilityLabel: string;
+  /** Localized screen-reader label for the close button (`si_cd_close`). */
+  readonly closeAccessibilityLabel: string;
 };
 
-const SHUTTER_SIZE = 72;
-const SHUTTER_INNER_SIZE = 56;
-const GALLERY_SIZE = 52;
-const CONTROL_GAP = 20;
+const SHUTTER_SIZE = 64;
+const SHUTTER_INNER_SIZE = 46;
+const GALLERY_SIZE = 56;
+const CONTROL_GAP = 24;
+const CLOSE_SIZE = 40;
+/** Trailing-edge inset for the landscape lane (spacing.large). */
+const LANE_EDGE = 24;
+/** Bottom inset for the portrait control row above the safe area (spacing.large). */
+const PORTRAIT_ROW_BOTTOM = 24;
+/** Top/bottom inset bounding the ✕ and the centred controls inside the lane. */
+const LANE_VERTICAL_PADDING = 16;
 
 /**
- * Document capture controls — manual shutter + gallery upload, a trailing-edge
- * column in landscape and a centred bottom row in portrait (matches the capture design).
+ * Document capture controls — manual shutter + gallery upload, plus the close ✕
+ * in landscape (laid out as a trailing-edge lane; portrait is a centred bottom
+ * row with the ✕ in the top chrome).
  */
 export function UseSmileIDDocumentCaptureControls(
   props: UseSmileIDDocumentCaptureControlsProps,
@@ -40,10 +53,33 @@ export function UseSmileIDDocumentCaptureControls(
   // Light-palette forced: overlay is locked to light mode so brand-blue reads over the dim feed.
   const theme = defaultLightTheme;
 
-  if (!props.capturing && !props.showManualShutter && !props.showGallery) {
+  const controlsVisible = props.showManualShutter || props.showGallery;
+  // The lane keeps the ✕ even when shutter/gallery hide (during capture); portrait
+  // renders nothing here once the controls are hidden.
+  const showCloseInLane = props.isLandscape && props.onClose !== undefined;
+  if (!controlsVisible && !showCloseInLane) {
     return null;
   }
 
+  const closeButton = props.onClose ? (
+    <Pressable
+      onPress={props.onClose}
+      accessibilityRole="button"
+      accessibilityLabel={props.closeAccessibilityLabel}
+      testID="si_document_close_button"
+      style={({ pressed }) => [
+        styles.closeButton,
+        {
+          backgroundColor: theme.colors.offBlack,
+          borderColor: theme.colors.backButtonBorder,
+          opacity: pressed ? 0.7 : 1,
+        },
+      ]}
+    >
+      <SiOutlineClose size={20} color={theme.colors.offWhite} />
+    </Pressable>
+  ) : null;
+
   const shutter = props.showManualShutter ? (
     <Pressable
       onPress={props.onManualShutter}
@@ -81,60 +117,88 @@ export function UseSmileIDDocumentCaptureControls(
     </Pressable>
   ) : null;
 
+  if (props.isLandscape) {
+    // Trailing-edge lane: ✕ at the top, shutter/gallery vertically centred
+    // between two flex spacers so the controls hold the lane's vertical centre.
+    return (
+      <SafeAreaView
+        edges={["top", "right", "bottom", "left"]}
+        style={styles.landscapeLane}
+        pointerEvents="box-none"
+        testID="si_document_capture_controls"
+      >
+        {/* Fixed-width slot keeps the ✕ on the shutter's centre-x even when the
+            shutter/gallery hide during capture (matches the native lane width). */}
+        <View style={styles.laneSlot}>{closeButton}</View>
+        <View style={styles.laneSpacer} />
+        {controlsVisible ? (
+          <View style={styles.landscapeControls}>
+            {shutter}
+            {gallery}
+          </View>
+        ) : null}
+        <View style={styles.laneSpacer} />
+      </SafeAreaView>
+    );
+  }
+
+  // Portrait: centred bottom row (gallery left of shutter).
   return (
-    <View
-      style={props.isLandscape ? styles.landscapeColumn : styles.portraitRow}
+    <SafeAreaView
+      edges={["top", "right", "bottom", "left"]}
+      style={styles.portraitRow}
       pointerEvents="box-none"
       testID="si_document_capture_controls"
     >
-      {props.capturing ? (
-        <UseSmileIDCaptureSpinner
-          color={theme.colors.ovalActive}
-          testID="si_document_capture_spinner"
-        />
-      ) : props.isLandscape ? (
-        // Landscape: shutter above gallery (trailing column).
-        <>
-          {shutter}
-          {gallery}
-        </>
-      ) : (
-        // Portrait: gallery left of shutter (bottom row).
-        <>
-          {gallery}
-          {shutter}
-        </>
-      )}
-    </View>
+      {gallery}
+      {shutter}
+    </SafeAreaView>
   );
 }
 
 const styles = StyleSheet.create({
-  landscapeColumn: {
+  // No fixed width: the lane sizes to its (≤ SHUTTER_SIZE-wide) content so the
+  // additive horizontal safe-area inset SHIFTS it inward instead of squeezing the
+  // controls (RN is border-box; padding inside a fixed width would clip them).
+  landscapeLane: {
     position: "absolute",
     top: 0,
     bottom: 0,
-    end: 24,
+    end: LANE_EDGE,
+    flexDirection: "column",
+    alignItems: "center",
+    paddingVertical: LANE_VERTICAL_PADDING,
+  },
+  laneSpacer: { flex: 1 },
+  laneSlot: { width: SHUTTER_SIZE, alignItems: "center" },
+  landscapeControls: {
     flexDirection: "column",
     alignItems: "center",
-    justifyContent: "center",
     gap: CONTROL_GAP,
   },
   portraitRow: {
     position: "absolute",
     start: 0,
     end: 0,
-    bottom: 96,
+    bottom: PORTRAIT_ROW_BOTTOM,
     flexDirection: "row",
     alignItems: "center",
     justifyContent: "center",
     gap: CONTROL_GAP * 1.6,
   },
+  closeButton: {
+    width: CLOSE_SIZE,
+    height: CLOSE_SIZE,
+    borderRadius: CLOSE_SIZE / 2,
+    borderWidth: 1,
+    alignItems: "center",
+    justifyContent: "center",
+  },
   shutterOuter: {
     width: SHUTTER_SIZE,
     height: SHUTTER_SIZE,
     borderRadius: SHUTTER_SIZE / 2,
-    borderWidth: 3,
+    borderWidth: 4,
     borderColor: "#FFFFFF",
     alignItems: "center",
     justifyContent: "center",