@smileid/usesmileid 12.0.0-beta01

package/src/presentation/flow/analytics/__tests__/use_smile_id_analytics_event.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  UseSmileIDAnalyticsEventTypes,
+  UseSmileIDAnalyticsParamKeys,
+  UseSmileIDAnalyticsReasons,
+  UseSmileIDAnalyticsScreenNames,
+} from "../use_smile_id_analytics_event";
+
+/**
+ * Locks down the wire-format identifiers in
+ * `UseSmileIDAnalyticsEventTypes` / `…ParamKeys` / `…Reasons` /
+ * `…ScreenNames`. Partner dashboards aggregate on the literal string
+ * values — a typo or accidental rename here would silently shatter
+ * their aggregations.
+ *
+ * Renaming a value here is a wire-format break — partner dashboards
+ * will silently lose aggregations until the literal is restored.
+ */
+describe("UseSmileIDAnalyticsEventTypes", () => {
+  it("event type wire strings are stable", () => {
+    expect(UseSmileIDAnalyticsEventTypes.flowStarted).toBe("flow_started");
+    expect(UseSmileIDAnalyticsEventTypes.screenViewed).toBe("screen_viewed");
+    expect(UseSmileIDAnalyticsEventTypes.consentCaptured).toBe(
+      "consent_captured",
+    );
+    expect(UseSmileIDAnalyticsEventTypes.selfieCaptured).toBe(
+      "selfie_captured",
+    );
+    expect(UseSmileIDAnalyticsEventTypes.documentCaptured).toBe(
+      "document_captured",
+    );
+    expect(UseSmileIDAnalyticsEventTypes.retakeRequested).toBe(
+      "retake_requested",
+    );
+    expect(UseSmileIDAnalyticsEventTypes.jobSubmitted).toBe("job_submitted");
+    expect(UseSmileIDAnalyticsEventTypes.flowCompleted).toBe("flow_completed");
+  });
+
+  it("capture-quality event types expose stable wire names", () => {
+    expect(UseSmileIDAnalyticsEventTypes.selfieSessionRestarted).toBe(
+      "selfie_session_restarted",
+    );
+    expect(UseSmileIDAnalyticsEventTypes.selfieFrameRejected).toBe(
+      "selfie_frame_rejected",
+    );
+  });
+});
+
+describe("UseSmileIDAnalyticsParamKeys", () => {
+  it("param key wire strings are stable", () => {
+    expect(UseSmileIDAnalyticsParamKeys.jobType).toBe("job_type");
+    expect(UseSmileIDAnalyticsParamKeys.screenName).toBe("screen_name");
+    expect(UseSmileIDAnalyticsParamKeys.sessionId).toBe("session_id");
+    expect(UseSmileIDAnalyticsParamKeys.timestamp).toBe("timestamp");
+    expect(UseSmileIDAnalyticsParamKeys.documentSide).toBe("document_side");
+    expect(UseSmileIDAnalyticsParamKeys.decision).toBe("decision");
+    expect(UseSmileIDAnalyticsParamKeys.livenessImageCount).toBe(
+      "liveness_image_count",
+    );
+    expect(UseSmileIDAnalyticsParamKeys.attempt).toBe("attempt");
+    expect(UseSmileIDAnalyticsParamKeys.jobId).toBe("job_id");
+    expect(UseSmileIDAnalyticsParamKeys.result).toBe("result");
+    expect(UseSmileIDAnalyticsParamKeys.errorMessage).toBe("error_message");
+  });
+
+  it("capture-quality param keys match the native SDKs", () => {
+    expect(UseSmileIDAnalyticsParamKeys.reason).toBe("reason");
+    expect(UseSmileIDAnalyticsParamKeys.framesDiscarded).toBe(
+      "frames_discarded",
+    );
+    expect(UseSmileIDAnalyticsParamKeys.durationMs).toBe("duration_ms");
+    expect(UseSmileIDAnalyticsParamKeys.iou).toBe("iou");
+    expect(UseSmileIDAnalyticsParamKeys.probability).toBe("probability");
+  });
+});
+
+describe("UseSmileIDAnalyticsScreenNames", () => {
+  it("screen-name wire strings are stable", () => {
+    expect(UseSmileIDAnalyticsScreenNames.consent).toBe("consent");
+    expect(UseSmileIDAnalyticsScreenNames.instructions).toBe("instructions");
+    expect(UseSmileIDAnalyticsScreenNames.capture).toBe("capture");
+    expect(UseSmileIDAnalyticsScreenNames.preview).toBe("preview");
+    expect(UseSmileIDAnalyticsScreenNames.processing).toBe("processing");
+  });
+});
+
+describe("UseSmileIDAnalyticsReasons", () => {
+  it("reason wire strings match the native SDKs", () => {
+    // The native ML pipeline classifies every rejected frame /
+    // restarted session against one of these reason codes; partner
+    // dashboards group by them. Drift here would silently un-group
+    // a category.
+    expect(UseSmileIDAnalyticsReasons.outOfFrame).toBe("out_of_frame");
+    expect(UseSmileIDAnalyticsReasons.timeout).toBe("timeout");
+    expect(UseSmileIDAnalyticsReasons.qualityDropTimeout).toBe(
+      "quality_drop_timeout",
+    );
+    expect(UseSmileIDAnalyticsReasons.multipleFacesLost).toBe(
+      "multiple_faces_lost",
+    );
+    expect(UseSmileIDAnalyticsReasons.motionBlur).toBe("motion_blur");
+    expect(UseSmileIDAnalyticsReasons.notSmiling).toBe("not_smiling");
+  });
+});

package/src/presentation/flow/analytics/use_smile_id_analytics_event.ts

@@ -0,0 +1,83 @@
+/**
+ * Analytics event surfaced via the top-level `onAnalyticsEvent`
+ * callback on the builder. The `extras` shape is a flat
+ * `Record<string, string>`.
+ *
+ * The event type strings + param keys + reason codes are wire-format
+ * contracts — partner dashboards aggregate on the literal values, so
+ * entries here may only be added, never renamed or removed.
+ */
+
+/** Stable event type identifiers. */
+export const UseSmileIDAnalyticsEventTypes = {
+  flowStarted: "flow_started",
+  screenViewed: "screen_viewed",
+  consentCaptured: "consent_captured",
+  selfieCaptured: "selfie_captured",
+  documentCaptured: "document_captured",
+  retakeRequested: "retake_requested",
+  jobSubmitted: "job_submitted",
+  flowCompleted: "flow_completed",
+  /**
+   * Selfie capture session restarts after Unsatisfied. Extras:
+   * `reason`, `frames_discarded`, `duration_ms`.
+   */
+  selfieSessionRestarted: "selfie_session_restarted",
+  /**
+   * Per-frame liveness rejection. Extras: `reason` plus optional
+   * `iou` / `probability`.
+   */
+  selfieFrameRejected: "selfie_frame_rejected",
+} as const;
+
+export type UseSmileIDAnalyticsEventType =
+  (typeof UseSmileIDAnalyticsEventTypes)[keyof typeof UseSmileIDAnalyticsEventTypes];
+
+/** Extra parameter key constants for `UseSmileIDAnalyticsEvent.extras`. */
+export const UseSmileIDAnalyticsParamKeys = {
+  jobType: "job_type",
+  screenName: "screen_name",
+  sessionId: "session_id",
+  timestamp: "timestamp",
+  documentSide: "document_side",
+  decision: "decision",
+  livenessImageCount: "liveness_image_count",
+  attempt: "attempt",
+  jobId: "job_id",
+  result: "result",
+  errorMessage: "error_message",
+  reason: "reason",
+  framesDiscarded: "frames_discarded",
+  durationMs: "duration_ms",
+  iou: "iou",
+  probability: "probability",
+} as const;
+
+/** Screen name constants used in the `screen_name` extras key. */
+export const UseSmileIDAnalyticsScreenNames = {
+  consent: "consent",
+  instructions: "instructions",
+  capture: "capture",
+  preview: "preview",
+  processing: "processing",
+} as const;
+
+/**
+ * Stable wire-identifier strings for the `reason` extras key.
+ * Partner dashboards aggregate on these — never change a value here
+ * without bumping the wire format.
+ */
+export const UseSmileIDAnalyticsReasons = {
+  outOfFrame: "out_of_frame",
+  timeout: "timeout",
+  qualityDropTimeout: "quality_drop_timeout",
+  multipleFacesLost: "multiple_faces_lost",
+  motionBlur: "motion_blur",
+  notSmiling: "not_smiling",
+} as const;
+
+export type UseSmileIDAnalyticsEvent = {
+  readonly type: UseSmileIDAnalyticsEventType;
+  /** Flat string→string map. Always includes `session_id` and `timestamp`. */
+  readonly extras: Readonly<Record<string, string>>;
+};

package/src/presentation/flow/config/flow_configuration.ts

@@ -0,0 +1,12 @@
+import type { FlowConfigurationSnapshot } from "../dsl/use_smile_id_flow_builder";
+
+/**
+ * Top-level flow configuration. Built by `useSmileIDBuilder` (or
+ * `new UseSmileIDFlowBuilder()`); partners hand the snapshot to
+ * `<UseSmileIDBuilder>`.
+ *
+ * The shape lives in `dsl/use_smile_id_flow_builder.ts` as
+ * `FlowConfigurationSnapshot`; this alias preserves the canonical
+ * type name partners import.
+ */
+export type FlowConfiguration = FlowConfigurationSnapshot;

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

@@ -0,0 +1,161 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  AnalyzerFactoryKey,
+  ScanPerformanceProfile,
+} from "@smileid/usesmileid_bridge";
+import type { FaceAnalyzer } from "@smileid/usesmileid_platform_interface";
+import { AnalyzerRegistryBuilder, FaceAnalyzerScope } from "../ml_builder";
+import { CaptureType } from "../../../../../core/models/ml_config";
+
+function stubFaceAnalyzer(
+  key: AnalyzerFactoryKey = AnalyzerFactoryKey.VisionFace,
+): FaceAnalyzer {
+  return {
+    kind: "face",
+    key,
+    frameProcessorPluginName: "UseSmileIDVisionFaceFrameProcessor",
+    configure: vi.fn(),
+    reset: vi.fn(),
+    flush: vi.fn(),
+    close: vi.fn(),
+  };
+}
+
+describe("FaceAnalyzerScope.toFaceConfig", () => {
+  it("returns undefined when no analyzer was added", () => {
+    // Partner opened the scope but never called `.add(...)`; nothing
+    // for the orchestrator to push at the bridge. Falls back through
+    // the registry's `selfieConfig` being absent.
+    const scope = new FaceAnalyzerScope();
+    expect(scope.toFaceConfig()).toBeUndefined();
+  });
+
+  it("lifts the Balanced default profile into a wire FaceConfig", () => {
+    // Balanced ships 8 samples at 350ms interval (yields 1 selfie + 7
+    // liveness frames — the server's `liveness_images >= 6` floor
+    // requires the 7-frame liveness count).
+    const scope = new FaceAnalyzerScope();
+    scope.add(stubFaceAnalyzer(AnalyzerFactoryKey.MLKitFace));
+
+    expect(scope.toFaceConfig()).toMatchObject({
+      selfieCaptureTimeout: 100_000,
+      numSamples: 8,
+      sampleInterval: 350,
+      stayInFoundDuration: 3_000,
+      analyzerFactoryKey: AnalyzerFactoryKey.MLKitFace,
+    });
+  });
+
+  it("mirrors a custom ScanPerformanceProfile", () => {
+    // HighQuality is the one with the real trade-off post-Phase-0:
+    // 6 samples, 500ms interval (Balanced is 8 / 350).
+    const scope = new FaceAnalyzerScope();
+    scope.add(stubFaceAnalyzer());
+    scope.scanPerformanceProfile = ScanPerformanceProfile.HighQuality;
+
+    const config = scope.toFaceConfig()!;
+    expect(config.selfieCaptureTimeout).toBe(150_000);
+    expect(config.numSamples).toBe(6);
+    expect(config.sampleInterval).toBe(500);
+  });
+
+  it("includes only the FaceDetectorConfig fields the partner set", () => {
+    // Critical: the wire schema treats `undefined` as "use native
+    // default". Spreading every field unconditionally (even undefined
+    // ones) would overwrite the native default with `null`, silently
+    // changing behaviour. Test pins the spread-only-when-defined
+    // semantics.
+    const scope = new FaceAnalyzerScope();
+    scope.add(stubFaceAnalyzer());
+    scope.faceDetectorConfig = { minFillThreshold: 0.18 };
+
+    const config = scope.toFaceConfig()!;
+    expect(config.minFillThreshold).toBe(0.18);
+    expect(config.maxFillThreshold).toBeUndefined();
+    expect(config.centerToleranceX).toBeUndefined();
+  });
+
+  it("forwards the full FaceDetectorConfig field set", () => {
+    // The wire schema + native converters support the full threshold set;
+    // partners must be able to tune all of them, not just the fill/centre
+    // subset.
+    const scope = new FaceAnalyzerScope();
+    scope.add(stubFaceAnalyzer());
+    scope.faceDetectorConfig = {
+      motionBlurMinIou: 0.9,
+      motionBlurMinDuration: 120,
+      minTopPadding: 0.08,
+      minFaceBoundsThreshold: 0.1,
+      maxFaceBoundsThreshold: 0.9,
+      minSmileProbability: 0.6,
+    };
+    const config = scope.toFaceConfig()!;
+    expect(config.motionBlurMinIou).toBe(0.9);
+    expect(config.motionBlurMinDuration).toBe(120);
+    expect(config.minTopPadding).toBe(0.08);
+    expect(config.minFaceBoundsThreshold).toBe(0.1);
+    expect(config.maxFaceBoundsThreshold).toBe(0.9);
+    expect(config.minSmileProbability).toBe(0.6);
+  });
+
+  it("defaults faceDetectorMode to the 'default' preset token", () => {
+    // No explicit mode → "default", which the native backend resolves to its
+    // own engine-calibrated preset.
+    const scope = new FaceAnalyzerScope();
+    scope.add(stubFaceAnalyzer());
+    expect(scope.toFaceConfig()!.faceDetectorMode).toBe("default");
+  });
+
+  it("forwards an explicit faceDetectorMode token", () => {
+    const scope = new FaceAnalyzerScope();
+    scope.add(stubFaceAnalyzer());
+    scope.detectorMode = "low";
+    expect(scope.toFaceConfig()!.faceDetectorMode).toBe("low");
+  });
+
+  it("propagates the analyzer's wire key into analyzerFactoryKey", () => {
+    // Multi-backend selection: the registered analyzer carries the
+    // identifier the native registry resolves on. The wire field must
+    // round-trip exactly.
+    const scope = new FaceAnalyzerScope();
+    scope.add(stubFaceAnalyzer(AnalyzerFactoryKey.HuaweiFace));
+    expect(scope.toFaceConfig()!.analyzerFactoryKey).toBe(
+      AnalyzerFactoryKey.HuaweiFace,
+    );
+  });
+});
+
+describe("AnalyzerRegistryBuilder", () => {
+  it("snapshots the selfie scope into selfieConfig at build time", () => {
+    // The registry stores BOTH the analyzer (for `.configure() / .close()`
+    // routing) AND the pre-built wire FaceConfig (so the orchestrator
+    // doesn't reach into the builder). This separation matches the
+    // Flutter `CaptureTypeAnalyzerBuilder` model.
+    const analyzer = stubFaceAnalyzer(AnalyzerFactoryKey.MLKitFace);
+    const builder = new AnalyzerRegistryBuilder();
+    builder.forCaptureType(CaptureType.selfie, (face) => {
+      face.add(analyzer);
+      face.scanPerformanceProfile = ScanPerformanceProfile.Fast;
+    });
+
+    const registry = builder.build();
+    expect(registry.selfie).toBe(analyzer);
+    expect(registry.selfieConfig).toMatchObject({
+      analyzerFactoryKey: AnalyzerFactoryKey.MLKitFace,
+      numSamples: 2,
+      selfieCaptureTimeout: 50_000,
+    });
+  });
+
+  it("omits selfieConfig when no analyzer was added", () => {
+    // Partner opened the scope but never called `.add(...)` —
+    // registry stays bare so the orchestrator's `?.selfie` guard fires.
+    const builder = new AnalyzerRegistryBuilder();
+    builder.forCaptureType(CaptureType.selfie, () => {
+      /* no add() call */
+    });
+    const registry = builder.build();
+    expect(registry.selfie).toBeUndefined();
+    expect(registry.selfieConfig).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,102 @@
+import { describe, expect, it } from "vitest";
+import { ThemeConfigBuilder } from "../theme_builder";
+import { defaultDarkTheme, defaultLightTheme } from "../../../../theme/theme";
+
+describe("ThemeConfigBuilder — partner overrides reach canonical token keys", () => {
+  it("maps every brand override to the canonical color key on both variants", () => {
+    // Each partner-supplied AdaptiveColor lands on its canonical
+    // token in both the light and dark resolved variants.
+    const themeBuilder = new ThemeConfigBuilder();
+    themeBuilder.primaryColor = themeBuilder.color("#001096", "#7B92FF");
+    themeBuilder.primaryForeground = themeBuilder.color("#F0F0F0", "#0F0F0F");
+    themeBuilder.secondaryColor = themeBuilder.color("#FF0000", "#FF7777");
+    themeBuilder.accentColor = themeBuilder.color("#00FF00", "#77FF77");
+
+    const bundle = themeBuilder.build();
+    expect(bundle.light.colors.primary).toBe("#001096");
+    expect(bundle.dark.colors.primary).toBe("#7B92FF");
+    expect(bundle.light.colors.primaryForeground).toBe("#F0F0F0");
+    expect(bundle.dark.colors.primaryForeground).toBe("#0F0F0F");
+    expect(bundle.light.colors.secondary).toBe("#FF0000");
+    expect(bundle.dark.colors.secondary).toBe("#FF7777");
+    expect(bundle.light.colors.accent).toBe("#00FF00");
+    expect(bundle.dark.colors.accent).toBe("#77FF77");
+  });
+
+  it("maps shape overrides (buttonShape → buttonRadius, cardShape → cardRadius)", () => {
+    // Shapes are not adaptive — same number lands on both variants.
+    const themeBuilder = new ThemeConfigBuilder();
+    themeBuilder.buttonShape = 16;
+    themeBuilder.cardShape = 4;
+
+    const bundle = themeBuilder.build();
+    expect(bundle.light.shapes.buttonRadius).toBe(16);
+    expect(bundle.dark.shapes.buttonRadius).toBe(16);
+    expect(bundle.light.shapes.cardRadius).toBe(4);
+    expect(bundle.dark.shapes.cardRadius).toBe(4);
+  });
+
+  it("preserves canonical defaults for tokens the partner did not override", () => {
+    // Partner overrides `primaryColor` only — the other tokens keep
+    // their canonical values on each variant.
+    const themeBuilder = new ThemeConfigBuilder();
+    themeBuilder.primaryColor = themeBuilder.color("#001096", "#7B92FF");
+
+    const bundle = themeBuilder.build();
+    expect(bundle.light.colors.primary).toBe("#001096");
+    expect(bundle.light.colors.primaryForeground).toBe(
+      defaultLightTheme.colors.primaryForeground,
+    );
+    expect(bundle.light.colors.secondary).toBe(
+      defaultLightTheme.colors.secondary,
+    );
+    expect(bundle.light.colors.accent).toBe(defaultLightTheme.colors.accent);
+    expect(bundle.light.colors.background).toBe(
+      defaultLightTheme.colors.background,
+    );
+    expect(bundle.dark.colors.primary).toBe("#7B92FF");
+    expect(bundle.dark.colors.primaryForeground).toBe(
+      defaultDarkTheme.colors.primaryForeground,
+    );
+    expect(bundle.dark.colors.background).toBe(
+      defaultDarkTheme.colors.background,
+    );
+  });
+
+  it("emits a frozen theme bundle so accidental mutation surfaces immediately", () => {
+    const bundle = new ThemeConfigBuilder().build();
+    expect(Object.isFrozen(bundle)).toBe(true);
+    expect(Object.isFrozen(bundle.light)).toBe(true);
+    expect(Object.isFrozen(bundle.dark)).toBe(true);
+  });
+
+  it("does not write phantom keys from the obsolete pre-fix mapping", () => {
+    // Regression guard: a typo'd refactor that re-introduces
+    // `onPrimary` / `surface` / `success` keys would silently land
+    // them on either variant. Both must stay clean.
+    const themeBuilder = new ThemeConfigBuilder();
+    themeBuilder.primaryForeground = themeBuilder.color("#F0F0F0", "#0F0F0F");
+    themeBuilder.secondaryColor = themeBuilder.color("#FF0000", "#FF7777");
+    themeBuilder.accentColor = themeBuilder.color("#00FF00", "#77FF77");
+
+    const bundle = themeBuilder.build();
+    for (const variant of [bundle.light, bundle.dark]) {
+      const colors = variant.colors as Record<string, unknown>;
+      expect(colors.onPrimary).toBeUndefined();
+      expect(colors.surface).toBeUndefined();
+      expect(colors.success).toBeUndefined();
+    }
+  });
+
+  it("treats an unset override as missing — emits canonical defaults on both variants", () => {
+    const bundle = new ThemeConfigBuilder().build();
+    expect(bundle.light).toEqual(defaultLightTheme);
+    expect(bundle.dark).toEqual(defaultDarkTheme);
+  });
+
+  it("color() helper produces a frozen AdaptiveColor pair", () => {
+    const pair = new ThemeConfigBuilder().color("#1A73E8", "#4DA3FF");
+    expect(pair).toEqual({ light: "#1A73E8", dark: "#4DA3FF" });
+    expect(Object.isFrozen(pair)).toBe(true);
+  });
+});

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

@@ -0,0 +1,22 @@
+import type { ConfigOptions } from "../../../../core/models/config";
+
+/**
+ * `b.config((c) => { c.enableCrashReporting = false; ... })`
+ *
+ * Mutable receiver — the closure assigns properties; `build()`
+ * snapshots them into a frozen `ConfigOptions` with every field
+ * populated.
+ */
+export class UseSmileIDConfigBuilder {
+  enableCrashReporting = true;
+  enableDebugMode = false;
+  allowOfflineMode = false;
+
+  build(): ConfigOptions {
+    return Object.freeze({
+      enableCrashReporting: this.enableCrashReporting,
+      enableDebugMode: this.enableDebugMode,
+      allowOfflineMode: this.allowOfflineMode,
+    });
+  }
+}

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

@@ -0,0 +1,201 @@
+import type {
+  FaceAnalyzer,
+  DocumentAnalyzer,
+} from "@smileid/usesmileid_platform_interface";
+import {
+  ScanPerformanceProfile,
+  type FaceConfig,
+  type FaceDetectorConfig,
+  type FaceDetectorMode,
+} from "@smileid/usesmileid_bridge";
+import {
+  CaptureType,
+  type AnalyzerRegistry,
+  type MLConfig,
+} from "../../../../core/models/ml_config";
+
+/**
+ * `b.ml((m) => { m.analyzers((a) => { a.forCaptureType(CaptureType.selfie, (face) => face.add(useSmileIDVisionFace)); }); })`
+ *
+ * Shape: `ml → analyzers → forCaptureType(type, callback) → add(analyzer)`
+ *
+ * Each provider package (`usesmileid_vision_face`,
+ * `usesmileid_mlkit_face`, …) exports a ready-to-use `FaceAnalyzer`
+ * / `DocumentAnalyzer` value. Partners register them per capture
+ * type via `forCaptureType`.
+ *
+ * Type-safety note: distinct `Face*` and `Document*` scope classes
+ * prevent the partner from setting the wrong slot inside a
+ * `forCaptureType` closure. Without this, a typo like
+ * `forCaptureType(CaptureType.selfie, (a) => a.documentAnalyzer = ...)` would
+ * silently drop the document analyzer and leave the face slot empty —
+ * the orchestrator would then refuse to run face capture with no
+ * clear cause. Distinct scopes block that at compile time.
+ */
+
+export class FaceAnalyzerScope {
+  /** Register the face analyzer for this scope. */
+  add(analyzer: FaceAnalyzer): void {
+    this._analyzer = analyzer;
+  }
+  /** @internal */
+  _analyzer?: FaceAnalyzer;
+
+  /**
+   * Scan-loop tuning preset (Fast / Balanced / HighQuality). Default is
+   * `Balanced`; the orchestrator lifts the field into `FaceConfig` at
+   * configure time.
+   */
+  scanPerformanceProfile: ScanPerformanceProfile =
+    ScanPerformanceProfile.Balanced;
+
+  /**
+   * Face-detection preset. A token (`"performance"` / `"default"` / `"low"`)
+   * the native backend resolves to its own engine-calibrated thresholds;
+   * defaults to `"default"`. Set individual {@link faceDetectorConfig} fields
+   * to override specific thresholds on top of the resolved preset.
+   */
+  detectorMode: FaceDetectorMode = "default";
+
+  /**
+   * Fine-grained face-detector thresholds. Omit to use the native
+   * session's platform-tuned defaults — partners typically leave this
+   * `undefined` and only set it for specific device/lighting
+   * constraints.
+   */
+  faceDetectorConfig?: FaceDetectorConfig;
+
+  /**
+   * Lift the DSL state into the wire-shape `FaceConfig` that
+   * `FaceAnalyzer.configure()` consumes.
+   *
+   * Returns `undefined` when no analyzer has been registered — callers
+   * skip the `configure()` call in that case rather than pushing a partial
+   * config at the native side.
+   *
+   * @internal
+   */
+  toFaceConfig(): FaceConfig | undefined {
+    const analyzer = this._analyzer;
+    if (!analyzer) return undefined;
+    const profile = this.scanPerformanceProfile;
+    const detector = this.faceDetectorConfig;
+    return {
+      selfieCaptureTimeout: profile.timeoutMs,
+      numSamples: profile.numSamples,
+      sampleInterval: profile.sampleIntervalMs,
+      stayInFoundDuration: profile.stayInFoundMs,
+      // Detection preset token. The native backend resolves this to its own
+      // engine-calibrated thresholds; the explicit fields below (when set)
+      // are overlaid on top of that resolved preset.
+      faceDetectorMode: this.detectorMode,
+      // Detector thresholds — spread only when the partner set them; the
+      // wire schema treats `undefined` as "use the native default".
+      ...(detector?.minFillThreshold !== undefined
+        ? { minFillThreshold: detector.minFillThreshold }
+        : {}),
+      ...(detector?.maxFillThreshold !== undefined
+        ? { maxFillThreshold: detector.maxFillThreshold }
+        : {}),
+      ...(detector?.faceDetectorMinScore !== undefined
+        ? { faceDetectorMinScore: detector.faceDetectorMinScore }
+        : {}),
+      ...(detector?.centerToleranceX !== undefined
+        ? { centerToleranceX: detector.centerToleranceX }
+        : {}),
+      ...(detector?.centerToleranceY !== undefined
+        ? { centerToleranceY: detector.centerToleranceY }
+        : {}),
+      ...(detector?.motionBlurMinIou !== undefined
+        ? { motionBlurMinIou: detector.motionBlurMinIou }
+        : {}),
+      ...(detector?.motionBlurMinDuration !== undefined
+        ? { motionBlurMinDuration: detector.motionBlurMinDuration }
+        : {}),
+      ...(detector?.minTopPadding !== undefined
+        ? { minTopPadding: detector.minTopPadding }
+        : {}),
+      ...(detector?.minFaceBoundsThreshold !== undefined
+        ? { minFaceBoundsThreshold: detector.minFaceBoundsThreshold }
+        : {}),
+      ...(detector?.maxFaceBoundsThreshold !== undefined
+        ? { maxFaceBoundsThreshold: detector.maxFaceBoundsThreshold }
+        : {}),
+      ...(detector?.minSmileProbability !== undefined
+        ? { minSmileProbability: detector.minSmileProbability }
+        : {}),
+      analyzerFactoryKey: analyzer.key,
+    };
+  }
+}
+
+export class DocumentAnalyzerScope {
+  /** Register the document analyzer for this scope. */
+  add(analyzer: DocumentAnalyzer): void {
+    this._analyzer = analyzer;
+  }
+  /** @internal */
+  _analyzer?: DocumentAnalyzer;
+}
+
+export class AnalyzerRegistryBuilder {
+  private _selfie?: FaceAnalyzer | undefined;
+  private _selfieConfig?: FaceConfig | undefined;
+  private _document?: DocumentAnalyzer | undefined;
+
+  /** Open a selfie-analyzer registration scope. */
+  forCaptureType(
+    captureType: CaptureType.selfie,
+    block: (a: FaceAnalyzerScope) => void,
+  ): void;
+  /** Open a document-analyzer registration scope. */
+  forCaptureType(
+    captureType: CaptureType.document,
+    block: (a: DocumentAnalyzerScope) => void,
+  ): void;
+  forCaptureType(
+    captureType: CaptureType,
+    block:
+      | ((a: FaceAnalyzerScope) => void)
+      | ((a: DocumentAnalyzerScope) => void),
+  ): void {
+    if (captureType === CaptureType.selfie) {
+      const scope = new FaceAnalyzerScope();
+      (block as (a: FaceAnalyzerScope) => void)(scope);
+      if (scope._analyzer) {
+        this._selfie = scope._analyzer;
+        // Snapshot the scope's DSL state into a wire `FaceConfig` now —
+        // build() time — so the orchestrator never has to reach into the
+        // builder.
+        this._selfieConfig = scope.toFaceConfig();
+      }
+      return;
+    }
+    const scope = new DocumentAnalyzerScope();
+    (block as (a: DocumentAnalyzerScope) => void)(scope);
+    if (scope._analyzer) this._document = scope._analyzer;
+  }
+
+  build(): AnalyzerRegistry {
+    return Object.freeze({
+      ...(this._selfie ? { selfie: this._selfie } : {}),
+      ...(this._selfieConfig ? { selfieConfig: this._selfieConfig } : {}),
+      ...(this._document ? { document: this._document } : {}),
+    });
+  }
+}
+
+export class UseSmileIDMLBuilder {
+  private _analyzers?: AnalyzerRegistryBuilder;
+
+  analyzers(block: (a: AnalyzerRegistryBuilder) => void): void {
+    if (!this._analyzers) this._analyzers = new AnalyzerRegistryBuilder();
+    block(this._analyzers);
+  }
+
+  build(): MLConfig {
+    return Object.freeze({
+      analyzers: this._analyzers ? this._analyzers.build() : Object.freeze({}),
+    });
+  }
+}