@smileid/usesmileid 12.0.0-beta01 → 12.0.0

package/src/__tests__/react_native_mock.tsx

@@ -99,6 +99,14 @@ export const I18nManager = { isRTL: false };
 
 export const useColorScheme = (): "light" | "dark" | null => "light";
 
+// Portrait window by default — the capture screen reads this for its
+// iOS preview-remount key (`cameraOrientationKey`); tests don't assert on
+// the key, so a stable portrait size just lets the component render.
+export const useWindowDimensions = (): { width: number; height: number } => ({
+  width: 390,
+  height: 844,
+});
+
 export const Platform = {
   OS: "ios" as const,
   select<T>(spec: { ios?: T; android?: T; default?: T }): T | undefined {

package/src/camera/camera_defaults.ts

@@ -1,23 +1,25 @@
 /** Static camera tuning defaults. */
 export const CameraDefaults = {
-  /** Focus running indicator visibility duration in ms. */
+  /** Focus running indicator visibility duration (ms). */
   focusRunningDurationMs: 600,
-  /** Focus settled indicator visibility duration in ms. */
+  /** Focus settled indicator visibility duration (ms). */
   focusSettledDurationMs: 500,
 
-  /** Pinned analysis-stream frame rate. 30 fps keeps head motion smooth and per-frame exposure low-ISO. */
+  /** Pinned analysis-stream frame rate; 30 fps keeps motion smooth at low ISO. */
   analysisTargetFps: 30,
-  /** Analysis-stream resolution (landscape). Matches the scan sessions' tuned input; higher stutters the frame-processor thread without improving detection. */
+  /** Selfie analysis resolution (4:3 — the face/smile heuristics are calibrated on it). */
   analysisTargetResolution: { width: 640, height: 480 } as const,
+  /** Document analysis resolution (16:9, matched to the visible preview so the guide-rect crop stays aligned). */
+  documentAnalysisResolution: { width: 1280, height: 720 } as const,
 
-  /** Longest-edge ceiling (px) for an imported document image; downscale-only, never upscale. Matches the native auto-capture resample target so every upload shares one byte policy. */
+  /** Longest-edge ceiling (px) for an imported document image; downscale-only. */
   documentMaxDimension: 1600,
-  /** JPEG compression quality (0.0–1.0, `expo-image-manipulator`'s `compress`) for imported document images; matches the auto-capture artifact quality. */
+  /** JPEG quality (0–1) for imported document images. */
   documentJpegQuality: 0.85,
-  /** Minimum shortest-edge (px) for a gallery document image; smaller is rejected pre-resample since upscaling yields unreadable artifacts. */
+  /** Minimum shortest-edge (px) for a gallery document image; smaller is rejected. */
   minGalleryDocumentDimensionPx: 600,
-  /** Default selfie JPEG width (px) when no `sdk_config` override is present; also the `image_width` metadata fallback. */
+  /** Default selfie JPEG width (px); also the `image_width` metadata fallback. */
   selfieJpegTargetWidth: 480,
-  /** Default selfie JPEG height (px) when no `sdk_config` override is present; also the `image_height` metadata fallback. */
+  /** Default selfie JPEG height (px); also the `image_height` metadata fallback. */
   selfieJpegTargetHeight: 640,
 } as const;

package/src/camera/orientation_degrees.ts

@@ -1,12 +1,11 @@
 import type { Orientation } from "react-native-vision-camera";
 
 /**
- * Map VisionCamera's gravity-derived device {@link Orientation} to the
- * clockwise degrees the native scan sessions expect (`0` = upright
- * portrait). Must reflect the physical device tilt — feed it from
- * `onOutputOrientationChanged` with `outputOrientation="device"`. Never
- * derive it from `frame.orientation`: that reports the sensor mounting,
- * not how the user is holding the phone.
+ * Map a VisionCamera {@link Orientation} to clockwise degrees (`0` = portrait).
+ * Feeds two callers: `onOutputOrientationChanged` (gravity tilt → the upright
+ * validator) and `onPreviewOrientationChanged` (locked viewport axis → the
+ * document `viewportOrientation` the frame processor uprights the capture to).
+ * Never use `frame.orientation` — that is the fixed sensor mounting.
  */
 export function orientationToDegrees(orientation: Orientation): number {
   switch (orientation) {

package/src/core/models/__tests__/document_type.test.ts

@@ -5,21 +5,23 @@ import { DocumentType } from "../document_type";
 // / orientation drive both copy and capture behaviour). Pin them exactly so a
 // change forces a deliberate decision here and in the sibling SDKs.
 describe("DocumentType presets", () => {
-  it("SouthAfricaGreenBook is a portrait, two-sided document", () => {
+  it("SouthAfricaGreenBook is a portrait, single-sided document", () => {
     expect(DocumentType.SouthAfricaGreenBook).toEqual({
       kind: "southAfricaGreenBook",
       displayName: "Green Book",
-      hasBackSide: true,
+      hasBackSide: false,
       orientation: "Portrait",
+      knownAspectRatio: 320 / 428,
     });
   });
 
-  it("Passport is a portrait, single-sided document", () => {
+  it("Passport is a landscape, single-sided document", () => {
     expect(DocumentType.Passport).toEqual({
       kind: "passport",
       displayName: "Passport",
       hasBackSide: false,
-      orientation: "Portrait",
+      orientation: "Landscape",
+      knownAspectRatio: 356 / 272,
     });
   });
 

package/src/core/models/document_capture_mode.ts

@@ -44,3 +44,30 @@ export const DocumentCaptureMode = {
     });
   },
 } as const;
+
+/**
+ * The wire token the server expects for the `auto_capture_enabled` builder-configuration field,
+ * keyed off the mode's `kind`. Lives with {@link DocumentCaptureMode} — its single source of
+ * truth — so the metadata layer maps the partner's typed choice straight onto the wire without a
+ * parallel enum. These exact strings are the server contract; changing them is a wire-breaking
+ * change. Not part of the public package surface (not re-exported from `index.ts`).
+ */
+export function autoCaptureWireValue(
+  mode: DocumentCaptureMode | undefined,
+): string {
+  switch (mode?.kind) {
+    case "autoCapture":
+      return "auto_capture_only";
+    case "manualCapture":
+      return "manual";
+    case "autoCaptureWithManualFallback":
+    case undefined:
+      return "autocapture_default";
+    default: {
+      // Exhaustiveness guard: a new DocumentCaptureMode kind fails to compile here
+      // until it's handled above (`mode` narrows to `never` once all kinds are covered).
+      const exhaustive: never = mode;
+      return exhaustive;
+    }
+  }
+}

package/src/core/models/document_type.ts

@@ -26,15 +26,17 @@ export type DocumentType =
 const SOUTH_AFRICA_GREEN_BOOK: DocumentType = Object.freeze({
   kind: "southAfricaGreenBook",
   displayName: "Green Book",
-  hasBackSide: true,
+  hasBackSide: false,
   orientation: "Portrait",
+  knownAspectRatio: 320 / 428,
 });
 
 const PASSPORT: DocumentType = Object.freeze({
   kind: "passport",
   displayName: "Passport",
   hasBackSide: false,
-  orientation: "Portrait",
+  orientation: "Landscape",
+  knownAspectRatio: 356 / 272,
 });
 
 /** Configurable fields for {@link DocumentType.GenericDocument}. */
@@ -47,9 +49,9 @@ export type GenericDocumentArgs = {
 
 /** Preset values and the `GenericDocument` factory for {@link DocumentType}. */
 export const DocumentType = {
-  /** South Africa Green Book — booklet-style, two-sided, portrait. */
+  /** South Africa Green Book — booklet-style, single-side, portrait. */
   SouthAfricaGreenBook: SOUTH_AFRICA_GREEN_BOOK,
-  /** Passport — single data page, no back side, portrait (provisional values). */
+  /** Passport — single data page, no back side, landscape. */
   Passport: PASSPORT,
   /** Catch-all without a preset; defaults to a landscape, two-sided "Document". */
   GenericDocument(args: GenericDocumentArgs = {}): DocumentType {

package/src/core/models/result.ts

@@ -1,31 +1,32 @@
 /**
- * A result type for SDK operations that makes error handling explicit.
+ * The outcome of an SDK operation: success with a value, failure with an
+ * error, or cancellation when the user exits the flow. Surfaced to
+ * partners through `onResult`.
  *
  * Partners never need to unwrap a `UseSmileIDResult` directly — all
  * errors are automatically surfaced through the `onResult` callback.
  * The discriminated union lets partner code `switch (result.status)`
- * and exhaust both branches without try/catch ceremony.
+ * and exhaust the branches without try/catch ceremony.
  */
 export type UseSmileIDResult<T> =
   | { readonly status: "success"; readonly value: T }
   | { readonly status: "failure"; readonly error: unknown }
   | { readonly status: "cancelled" };
 
-/** Construct a successful result carrying `value`. */
+/** A successful outcome carrying the resulting value. */
 export function success<T>(value: T): UseSmileIDResult<T> {
   return { status: "success", value };
 }
 
-/** Construct a failed result carrying `error`. */
+/** A failed outcome carrying the causing error. */
 export function failure<T>(error: unknown): UseSmileIDResult<T> {
   return { status: "failure", error };
 }
 
 /**
- * Construct a cancelled result — the user deliberately exited the flow
- * (e.g. back-pressed out of the first screen) without completing or
- * failing. Distinct from `failure` so partners can tell a user
- * cancellation apart from an error.
+ * The user deliberately exited the flow without completing or failing it
+ * (e.g. back-pressed out of the first screen) — distinct from a failure
+ * so cancellation can be handled separately.
  */
 export function cancelled<T>(): UseSmileIDResult<T> {
   return { status: "cancelled" };

package/src/data/api/interceptors/__tests__/smile_integrity_interceptor.test.ts

@@ -20,6 +20,7 @@ import {
   ATTESTATION_OPT_IN_KEY,
 } from "../smile_integrity_interceptor";
 import { REQUEST_MAC_HEADER } from "../smile_request_mac_interceptor";
+import { SecurityPolicy } from "../../../security/security_policy";
 
 /**
  * Pins down the integrity interceptor's wire shape:
@@ -51,7 +52,10 @@ describe("SmileIntegrityInterceptor", () => {
 
   beforeEach(() => {
     client = axios.create();
-    interceptor = new SmileIntegrityInterceptor();
+    // undefined bit-code is fail-secure: the attestation check is active, matching the pre-policy default.
+    interceptor = new SmileIntegrityInterceptor({
+      securityPolicy: SecurityPolicy.fromBitCode(undefined),
+    });
     interceptor.attach(client);
     warmUpAttestation = vi.fn();
     requestAttestationToken = vi.fn();
@@ -153,4 +157,36 @@ describe("SmileIntegrityInterceptor", () => {
     expect(ex.message).toBe("hello world");
     expect(encodeURIComponent(ex.message)).toBe("hello%20world");
   });
+
+  it("passes through without a nonce when policy disables attestation", async () => {
+    // bit-code 1: only payload signing (bit 0) set; the attestation bit (3) is off, so the token
+    // must not be requested even though the MAC header is present.
+    const localClient = axios.create();
+    new SmileIntegrityInterceptor({
+      securityPolicy: SecurityPolicy.fromBitCode(1),
+    }).attach(localClient);
+    const config = makeConfig({
+      [ATTESTATION_OPT_IN_KEY]: true,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } as any);
+    config.headers.set(REQUEST_MAC_HEADER, "mac-abc");
+
+    const handlers = (
+      localClient.interceptors.request as unknown as {
+        handlers: {
+          fulfilled?: (cfg: InternalAxiosRequestConfig) => unknown;
+        }[];
+      }
+    ).handlers;
+    let current = config;
+    for (let i = handlers.length - 1; i >= 0; i--) {
+      const handler = handlers[i]?.fulfilled;
+      if (typeof handler === "function") {
+        current = (await handler(current)) as InternalAxiosRequestConfig;
+      }
+    }
+
+    expect(current.headers.get(DEVICE_NONCE_HEADER)).toBeUndefined();
+    expect(requestAttestationToken).not.toHaveBeenCalled();
+  });
 });

package/src/data/api/interceptors/__tests__/smile_request_mac_interceptor.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it, beforeEach } from "vitest";
 import axios, { AxiosHeaders, type InternalAxiosRequestConfig } from "axios";
 
 import { SmileIDCryptoManager } from "../../../security/smile_id_crypto_manager";
+import { SecurityPolicy } from "../../../security/security_policy";
 import {
   SmileRequestMacInterceptor,
   REQUEST_MAC_HEADER,
@@ -26,7 +27,11 @@ describe("SmileRequestMacInterceptor", () => {
 
   beforeEach(() => {
     client = axios.create();
-    interceptor = new SmileRequestMacInterceptor({ cryptoManager });
+    // undefined bit-code is fail-secure: payload signing is active, matching the pre-policy default.
+    interceptor = new SmileRequestMacInterceptor({
+      cryptoManager,
+      securityPolicy: SecurityPolicy.fromBitCode(undefined),
+    });
     interceptor.attach(client);
   });
 
@@ -95,4 +100,57 @@ describe("SmileRequestMacInterceptor", () => {
     );
     expect(result.headers.get(REQUEST_MAC_HEADER)).toBeUndefined();
   });
+
+  /** Drive a one-interceptor client built with a specific policy. */
+  async function runWith(
+    policy: SecurityPolicy,
+    config: InternalAxiosRequestConfig,
+  ): Promise<InternalAxiosRequestConfig> {
+    const localClient = axios.create();
+    new SmileRequestMacInterceptor({
+      cryptoManager,
+      securityPolicy: policy,
+    }).attach(localClient);
+    const handlers = (
+      localClient.interceptors.request as unknown as {
+        handlers: {
+          fulfilled?: (cfg: InternalAxiosRequestConfig) => unknown;
+        }[];
+      }
+    ).handlers;
+    let current = config;
+    for (let i = handlers.length - 1; i >= 0; i--) {
+      const handler = handlers[i]?.fulfilled;
+      if (typeof handler === "function") {
+        current = (await handler(current)) as InternalAxiosRequestConfig;
+      }
+    }
+    return current;
+  }
+
+  it("leaves the request unsigned when the policy disables payload signing", async () => {
+    // bit-code 0: no bits set, so payload signing is off for this session.
+    const result = await runWith(
+      SecurityPolicy.fromBitCode(0),
+      makeConfig({
+        data: '{"hello":"world"}',
+        headers: new AxiosHeaders({ [REQUEST_TIMESTAMP_HEADER]: TIMESTAMP }),
+        [REQUEST_MAC_OPT_IN_KEY]: true,
+      } as Partial<InternalAxiosRequestConfig>),
+    );
+    expect(result.headers.get(REQUEST_MAC_HEADER)).toBeUndefined();
+  });
+
+  it("signs when the policy enables only payload signing", async () => {
+    // bit-code 1: bit 0 (payload signing) set; other behaviours off.
+    const result = await runWith(
+      SecurityPolicy.fromBitCode(1),
+      makeConfig({
+        data: '{"hello":"world"}',
+        headers: new AxiosHeaders({ [REQUEST_TIMESTAMP_HEADER]: TIMESTAMP }),
+        [REQUEST_MAC_OPT_IN_KEY]: true,
+      } as Partial<InternalAxiosRequestConfig>),
+    );
+    expect(result.headers.get(REQUEST_MAC_HEADER)).toBeDefined();
+  });
 });

package/src/data/api/interceptors/smile_auth_interceptor.ts

@@ -26,7 +26,7 @@ import type { TokenHolder } from "../auth/token_holder";
  * by the next outgoing request.
  */
 
-const SDK_VERSION = "12.0.0-beta01";
+const SDK_VERSION = "12.0.0";
 
 /**
  * Source-SDK identifier, suffixed with the runtime platform so the server can

package/src/data/api/interceptors/smile_integrity_interceptor.ts

@@ -2,6 +2,7 @@ import type { AxiosInstance, InternalAxiosRequestConfig } from "axios";
 
 import { Attestation, AttestationException } from "@smileid/usesmileid_bridge";
 
+import type { SecurityPolicy } from "../../security/security_policy";
 import { REQUEST_MAC_HEADER } from "./smile_request_mac_interceptor";
 
 /**
@@ -31,6 +32,11 @@ import { REQUEST_MAC_HEADER } from "./smile_request_mac_interceptor";
  * Warm-up lives outside the interceptor. Call `Attestation.warmUp()`
  * once at flow mount so the per-request `requestToken` call doesn't
  * pay the multi-second warm-up cost on every submission.
+ *
+ * Attestation is additionally gated by the server-driven {@link SecurityPolicy}:
+ * when the session's policy disables the device-attestation check, an opted-in
+ * request ships without a device nonce. The policy is fail-secure, so a token
+ * that omits the claim attests as before.
  */
 
 export const DEVICE_NONCE_HEADER = "smileid-device-nonce";
@@ -38,7 +44,17 @@ export const DEVICE_NONCE_HEADER = "smileid-device-nonce";
 /** Axios config key that opts a request into attestation stamping. */
 export const ATTESTATION_OPT_IN_KEY = "_useSmileIDAttestation";
 
+export type SmileIntegrityInterceptorOptions = {
+  readonly securityPolicy: SecurityPolicy;
+};
+
 export class SmileIntegrityInterceptor {
+  private readonly _securityPolicy: SecurityPolicy;
+
+  constructor(options: SmileIntegrityInterceptorOptions) {
+    this._securityPolicy = options.securityPolicy;
+  }
+
   attach(client: AxiosInstance): { request: number } {
     const requestId = client.interceptors.request.use(async (config) => {
       return this._onRequest(config);
@@ -55,6 +71,10 @@ export class SmileIntegrityInterceptor {
       ] === true;
     if (!optedIn) return config;
 
+    // Server-driven policy can switch device attestation off for this session; when it is off,
+    // ship the opted-in request without requesting a token.
+    if (!this._securityPolicy.isPlayIntegrityCheckActive()) return config;
+
     const macHeader = config.headers.get(REQUEST_MAC_HEADER);
     if (typeof macHeader !== "string") return config;
 

package/src/data/api/interceptors/smile_request_mac_interceptor.ts

@@ -2,6 +2,7 @@ import type { AxiosInstance, InternalAxiosRequestConfig } from "axios";
 
 import { SmileIDCryptoError } from "../../security/smile_id_crypto_error";
 import type { SmileIDCryptoManager } from "../../security/smile_id_crypto_manager";
+import type { SecurityPolicy } from "../../security/security_policy";
 
 /**
  * Stamps the `smileid-request-mac` header on every outbound request whose axios
@@ -18,6 +19,11 @@ import type { SmileIDCryptoManager } from "../../security/smile_id_crypto_manage
  * rather than signed against an invented timestamp.
  *
  * Requests without the opt-in flag pass through unchanged.
+ *
+ * Signing is additionally gated by the server-driven {@link SecurityPolicy}: when the session's
+ * policy disables payload signing, an opted-in request still ships, just unsigned — the same wire
+ * shape as an opt-out request. The policy is fail-secure, so a token that omits the claim signs as
+ * before.
  */
 
 export const REQUEST_MAC_HEADER = "smileid-request-mac";
@@ -28,13 +34,16 @@ export const REQUEST_MAC_OPT_IN_KEY = "_useSmileIDRequestMac";
 
 export type SmileRequestMacInterceptorOptions = {
   readonly cryptoManager: SmileIDCryptoManager;
+  readonly securityPolicy: SecurityPolicy;
 };
 
 export class SmileRequestMacInterceptor {
   private readonly _cryptoManager: SmileIDCryptoManager;
+  private readonly _securityPolicy: SecurityPolicy;
 
   constructor(options: SmileRequestMacInterceptorOptions) {
     this._cryptoManager = options.cryptoManager;
+    this._securityPolicy = options.securityPolicy;
   }
 
   attach(client: AxiosInstance): { request: number } {
@@ -53,6 +62,10 @@ export class SmileRequestMacInterceptor {
       ] === true;
     if (!optedIn) return config;
 
+    // Server-driven policy can switch payload signing off for this session; when it is off, ship
+    // the opted-in request unsigned and let the server apply its policy.
+    if (!this._securityPolicy.isPayloadSigningActive()) return config;
+
     const timestamp = config.headers.get(REQUEST_TIMESTAMP_HEADER);
     if (typeof timestamp !== "string") return config;
 

package/src/data/compression/__tests__/payload_compressor.test.ts

@@ -0,0 +1,200 @@
+import { ImageType, type ImageTypeId } from "@smileid/usesmileid_bridge";
+import { describe, expect, it } from "vitest";
+
+import {
+  type CompressibleAsset,
+  CompressibleAssets,
+} from "../compressible_asset";
+import {
+  base64Len,
+  PayloadCompressionConfig as C,
+} from "../payload_compression_config";
+import { PayloadCompressor } from "../payload_compressor";
+
+const mib = C.bytesPerMB;
+
+/** Encoded size scales linearly with quality: `size(q) = base * q`. */
+class FakeAsset implements CompressibleAsset {
+  recompressCount = 0;
+  private q: number;
+  constructor(
+    readonly imageType: ImageTypeId,
+    private readonly base: number,
+    startQuality: number,
+  ) {
+    this.q = startQuality;
+  }
+  encodedSize(): number {
+    return Math.trunc(this.base * this.q);
+  }
+  quality(): number {
+    return this.q;
+  }
+  async recompress(quality: number): Promise<void> {
+    this.q = quality;
+    this.recompressCount += 1;
+  }
+}
+
+describe("PayloadCompressor", () => {
+  it("base64Len matches ceil(n / 3) * 4", () => {
+    expect(base64Len(0)).toBe(0);
+    expect(base64Len(1)).toBe(4);
+    expect(base64Len(3)).toBe(4);
+    expect(base64Len(4)).toBe(8);
+    expect(base64Len(6)).toBe(8);
+    expect(base64Len(3_000_000)).toBe(Math.ceil(3_000_000 / 3) * 4);
+  });
+
+  it("raw and projected sizes sum images plus metadata", () => {
+    const assets = new CompressibleAssets({
+      selfie: new FakeAsset(ImageType.Selfie, 300_000, 1.0),
+      liveness: [new FakeAsset(ImageType.Liveness, 100_000, 1.0)],
+    });
+    const metadata = 50_000;
+    expect(PayloadCompressor.rawBundleSize(assets, metadata)).toBe(
+      300_000 + 100_000 + 50_000,
+    );
+    expect(PayloadCompressor.projectedEncodedSize(assets, metadata)).toBe(
+      base64Len(300_000) +
+        base64Len(100_000) +
+        metadata +
+        C.structuralOverheadBytes,
+    );
+  });
+
+  it("plan order Rule B - selfie over 1MB compresses faces first then back then front", () => {
+    const assets = new CompressibleAssets({
+      selfie: new FakeAsset(ImageType.Selfie, 2 * mib, 0.95),
+      liveness: [new FakeAsset(ImageType.Liveness, mib, 0.8)],
+      documentFront: new FakeAsset(ImageType.DocumentFront, mib, 0.85),
+      documentBack: new FakeAsset(ImageType.DocumentBack, mib, 0.85),
+    });
+    const plan = PayloadCompressor.buildCompressionPlan(assets);
+    expect(plan.map(([a]) => a.imageType)).toEqual([
+      ImageType.Selfie,
+      ImageType.Liveness,
+      ImageType.DocumentBack,
+      ImageType.DocumentFront,
+    ]);
+    expect(plan[0][1]).toBe(C.faceMinQ);
+    expect(plan[3][1]).toBe(C.docMinQ);
+  });
+
+  it("plan order Rule A - documents over 4MB compresses back, front, then faces", () => {
+    const assets = new CompressibleAssets({
+      selfie: new FakeAsset(ImageType.Selfie, 500_000, 0.95),
+      documentFront: new FakeAsset(ImageType.DocumentFront, 3 * mib, 0.9),
+      documentBack: new FakeAsset(ImageType.DocumentBack, 3 * mib, 0.9),
+    });
+    const plan = PayloadCompressor.buildCompressionPlan(assets);
+    expect(plan.map(([a]) => a.imageType)).toEqual([
+      ImageType.DocumentBack,
+      ImageType.DocumentFront,
+      ImageType.Selfie,
+    ]);
+  });
+
+  it("plan order generic - small selfie and docs uses faces then docs", () => {
+    const assets = new CompressibleAssets({
+      selfie: new FakeAsset(ImageType.Selfie, 400_000, 0.95),
+      documentFront: new FakeAsset(ImageType.DocumentFront, 400_000, 0.85),
+    });
+    const plan = PayloadCompressor.buildCompressionPlan(assets);
+    expect(plan.map(([a]) => a.imageType)).toEqual([
+      ImageType.Selfie,
+      ImageType.DocumentFront,
+    ]);
+  });
+
+  it("already small bundle is left untouched", async () => {
+    const selfie = new FakeAsset(ImageType.Selfie, mib, 0.95);
+    await PayloadCompressor.prepareBundleForTransmission(
+      new CompressibleAssets({ selfie }),
+      50_000,
+    );
+    expect(selfie.recompressCount).toBe(0);
+  });
+
+  it("over-budget bundle compresses under target and never breaches floors", async () => {
+    const selfie = new FakeAsset(
+      ImageType.Selfie,
+      Math.trunc((22 * mib) / 10),
+      0.95,
+    );
+    const liveness = [
+      new FakeAsset(ImageType.Liveness, Math.trunc((12 * mib) / 10), 0.8),
+      new FakeAsset(ImageType.Liveness, Math.trunc((12 * mib) / 10), 0.8),
+    ];
+    const assets = new CompressibleAssets({ selfie, liveness });
+    const metadata = Math.trunc((2 * mib) / 10);
+    await PayloadCompressor.prepareBundleForTransmission(assets, metadata);
+
+    expect(
+      PayloadCompressor.rawBundleSize(assets, metadata),
+    ).toBeLessThanOrEqual(C.rawFallback);
+    expect(selfie.quality()).toBeGreaterThanOrEqual(C.faceMinQ);
+    for (const frame of liveness)
+      expect(frame.quality()).toBeGreaterThanOrEqual(C.faceMinQ);
+  });
+
+  it("document-heavy bundle compresses back first and never breaches the doc floor", async () => {
+    const front = new FakeAsset(
+      ImageType.DocumentFront,
+      Math.trunc((23 * mib) / 10),
+      0.9,
+    );
+    const back = new FakeAsset(
+      ImageType.DocumentBack,
+      Math.trunc((23 * mib) / 10),
+      0.9,
+    );
+    const selfie = new FakeAsset(ImageType.Selfie, 400_000, 0.95);
+    const assets = new CompressibleAssets({
+      selfie,
+      documentFront: front,
+      documentBack: back,
+    });
+    await PayloadCompressor.prepareBundleForTransmission(assets, 100_000);
+    expect(back.quality()).toBeLessThanOrEqual(front.quality());
+    expect(front.quality()).toBeGreaterThanOrEqual(C.docMinQ);
+    expect(back.quality()).toBeGreaterThanOrEqual(C.docMinQ);
+    expect(
+      PayloadCompressor.rawBundleSize(assets, 100_000),
+    ).toBeLessThanOrEqual(C.rawTarget);
+  });
+
+  it("hard guarantee drops past the per-type floor to fit the relaxed cap", async () => {
+    // floor .45 -> 12MB*.45 = 5.4MB raw, still over the relaxed 4.5MB ceiling. The guarantee pass
+    // must step quality below faceMinQ until the bundle fits both caps.
+    const selfie = new FakeAsset(ImageType.Selfie, 12 * mib, 0.95);
+    const assets = new CompressibleAssets({ selfie });
+    await PayloadCompressor.prepareBundleForTransmission(assets, 100_000);
+    expect(
+      PayloadCompressor.rawBundleSize(assets, 100_000),
+    ).toBeLessThanOrEqual(C.rawFallback);
+    expect(
+      PayloadCompressor.projectedEncodedSize(assets, 100_000),
+    ).toBeLessThanOrEqual(C.hardEncodedCap);
+    expect(selfie.quality()).toBeLessThan(C.faceMinQ);
+    expect(selfie.quality()).toBeGreaterThanOrEqual(C.absoluteMinQ);
+  });
+
+  it("extreme bundle unreachable by quality drives to the absolute floor without throwing", async () => {
+    // So large that even absoluteMinQ leaves it over the cap (real JPEGs shrink far more than this
+    // linear fake). The guarantee pass drives to the absolute floor and ships — never loops forever.
+    const selfie = new FakeAsset(ImageType.Selfie, 80 * mib, 0.95);
+    const assets = new CompressibleAssets({ selfie });
+    await PayloadCompressor.prepareBundleForTransmission(assets, 100_000);
+    expect(selfie.quality()).toBe(C.absoluteMinQ);
+  });
+
+  it("bundle in fallback band with light metadata is accepted", async () => {
+    const selfie = new FakeAsset(ImageType.Selfie, 9 * mib, 0.95);
+    const assets = new CompressibleAssets({ selfie });
+    await PayloadCompressor.prepareBundleForTransmission(assets, 100_000);
+    const raw = PayloadCompressor.rawBundleSize(assets, 100_000);
+    expect(raw).toBeGreaterThan(C.rawTarget);
+    expect(raw).toBeLessThanOrEqual(C.rawFallback);
+  });
+});