@smileid/usesmileid 12.0.0-beta01

package/src/index.ts

@@ -0,0 +1,512 @@
+/**
+ * `usesmileid` — public-facing React Native (Expo) entry point
+ * for the UseSmileID v12 SDK.
+ *
+ * ML processing lives in the federated provider packages
+ * (`usesmileid_{mlkit,vision,huawei}_{face,document}`); this package
+ * owns configuration, state observation, and UI.
+ */
+
+// Top-level partner entry point — render-prop component that wraps
+// the closure-based block builder. Partners pass a `builder` prop
+// and the component owns build-and-dispatch internally; the
+// intermediate result type is internal.
+export { UseSmileIDBuilder } from "./presentation/flow/dsl/use_smile_id_builder";
+export { UseSmileIDFlowBuilder } from "./presentation/flow/dsl/use_smile_id_flow_builder";
+
+// Validation surface — `b.validate()` / `b.validateConsent(...)` and
+// the state types they return.
+export {
+  ValidationState,
+  type ValidationIssue,
+  type ValidationStateInvalid,
+} from "./presentation/flow/validation/validation_state";
+
+// Exception hierarchy — the typed errors carried by build-result
+// invalid issues and surfaced via `onResult.failure`. Each concrete
+// subclass holds a stable `errorCode` and `severity` so partner
+// tooling can pivot on either without parsing the message text.
+export {
+  BuilderValidationException,
+  ConsentDeniedException,
+  DuplicateScreenTypeException,
+  EmptyScreensBlockException,
+  InvalidConsentConfigException,
+  InvalidConsentInformationException,
+  InvalidDocumentCaptureConfigException,
+  InvalidFieldValueException,
+  InvalidJobTypeScreenConfigException,
+  InvalidMissingCaptureTypeException,
+  InvalidScreenOrderException,
+  InvalidSelfieCaptureConfigException,
+  LivenessFrameCountException,
+  IssueSeverity,
+  MissingCaptureForPreviewException,
+  MissingJobTypeException,
+  MissingMLConfigurationBlockException,
+  MissingNetworkConfigurationBlockException,
+  MissingPartnerConfigException,
+  MissingRequiredFieldException,
+  ProcessingCancelledException,
+  UseSmileIDAttestationException,
+  UseSmileIDBuilderException,
+  UseSmileIDCameraException,
+  UseSmileIDErrorCode,
+  UseSmileIDException,
+  UseSmileIDGeneralException,
+  UseSmileIDNetworkException,
+  UseSmileIDValidationException,
+} from "./core/exception";
+
+// Block builder classes — partners use them via the closure
+// (`b.config((c) => ...)`) but exporting them gives type access for
+// custom helper functions, tests, and IDE autocomplete docs.
+export { UseSmileIDConfigBuilder } from "./presentation/flow/dsl/builder/config_builder";
+export {
+  ThemeConfigBuilder,
+  type AdaptiveColor,
+  type ThemeConfiguration,
+} from "./presentation/flow/dsl/builder/theme_builder";
+export { UseSmileIDNetworkBuilder } from "./data/dsl/use_smile_id_network_builder";
+export {
+  ConfigBuilder,
+  LoggingConfigBuilder,
+  PartnerConfigBuilder,
+} from "./data/dsl/builder/config_builder";
+export { TimeoutConfigBuilder } from "./data/dsl/builder/timeout_config_builder";
+export { CacheConfigBuilder } from "./data/dsl/builder/cache_config_builder";
+export {
+  RetryConfigBuilder,
+  RetryStrategy,
+} from "./data/dsl/builder/retry_config_builder";
+export {
+  InterceptorConfigBuilder,
+  LoggingInterceptorBuilder,
+} from "./data/dsl/builder/interceptor_config_builder";
+export {
+  AnalyzerRegistryBuilder,
+  DocumentAnalyzerScope,
+  FaceAnalyzerScope,
+  UseSmileIDMLBuilder,
+} from "./presentation/flow/dsl/builder/ml_builder";
+export {
+  CaptureConfigBuilder,
+  CaptureType,
+  ConsentConfigBuilder,
+  DocumentCaptureConfigBuilder,
+  InstructionsConfigBuilder,
+  PreviewConfigBuilder,
+  ProcessingConfigBuilder,
+  ScreensBuilder,
+  SelfieCaptureConfigBuilder,
+  type ButtonSlot,
+  type ScreenSpec,
+  type ScreensConfig,
+} from "./presentation/flow/dsl/builder/screens_builder";
+
+// Flow
+export type { FlowConfiguration } from "./presentation/flow/config/flow_configuration";
+export {
+  FlowNavigationManager,
+  type CapturedArtifacts,
+  type FlowExitHandler,
+  type FlowExitReason,
+} from "./presentation/flow/flow_navigation_manager";
+export {
+  FlowNavigationProvider,
+  useFlowNavigation,
+  type FlowNavigationProviderProps,
+} from "./presentation/flow/flow_navigation_context";
+// Orchestrated screens — wrap each visual screen with the flow
+// navigation host. Partners typically don't import these directly
+// (the flow's screen renderer dispatches to them by `step.kind`);
+// exported for custom flow hosts and tests.
+export {
+  UseSmileIDOrchestratedScreenHost,
+  type UseSmileIDOrchestratedScreenHostProps,
+  type OrchestratedScreenHostContent,
+} from "./presentation/flow/screen/use_smile_id_orchestrated_screen_host";
+export {
+  OrchestratedInstructionsScreen,
+  type OrchestratedInstructionsScreenProps,
+} from "./presentation/flow/screen/orchestrated_instructions_screen";
+export {
+  OrchestratedConsentScreen,
+  type OrchestratedConsentScreenProps,
+} from "./presentation/flow/screen/orchestrated_consent_screen";
+export {
+  OrchestratedCaptureScreen,
+  type OrchestratedCaptureScreenProps,
+} from "./presentation/flow/screen/orchestrated_capture_screen";
+export {
+  OrchestratedPreviewScreen,
+  type OrchestratedPreviewScreenProps,
+} from "./presentation/flow/screen/orchestrated_preview_screen";
+export {
+  OrchestratedProcessingScreen,
+  type OrchestratedProcessingScreenProps,
+} from "./presentation/flow/screen/orchestrated_processing_screen";
+
+// Core. `UseSmileIDCrashReporting` lives in `usesmileid_bridge` so
+// every package in the workspace can reuse it; re-exported here to
+// keep the partner-facing import path unchanged.
+export { UseSmileIDCrashReporting } from "@smileid/usesmileid_bridge";
+
+// Localization — canonical English defaults + auto-locale registry.
+// Partners register translations once at app startup with
+// `UseSmileIDLocalizations.register(locale, overrides)`; the SDK
+// auto-resolves the device locale at flow mount via
+// `UseSmileIDLocalizations.forActiveLocale()`.
+export { UseSmileIDLocalizations } from "./l10n/use_smile_id_localizations";
+export {
+  UseSmileIDLocalizationsProvider,
+  useStableLocalizations,
+  useUseSmileIDLocalizations,
+  type UseSmileIDLocalizationsProviderProps,
+} from "./l10n/use_smile_id_localizations_provider";
+export { enStrings, type SiKey } from "./l10n/strings_en";
+
+// Camera — orchestrator class, preview component, defaults, types
+export { UseSmileIDCameraSystem } from "./camera/use_smile_id_camera_system";
+export {
+  UseSmileIDCameraPreview,
+  type UseSmileIDCameraPreviewProps,
+  type UseSmileIDFrameAnalysis,
+} from "./camera/use_smile_id_camera_preview";
+export {
+  useSmileIDFrameStream,
+  type UseSmileIDFrameStream,
+  type UseSmileIDFrameStreamOptions,
+} from "./camera/use_smile_id_frame_stream";
+export { CameraDefaults } from "./camera/camera_defaults";
+export { CameraLens } from "./camera/camera_lens";
+export {
+  FocusStates,
+  type FocusPoint,
+  type FocusState,
+} from "./camera/focus_state";
+export type {
+  CameraPreviewImage,
+  ViewBounds,
+} from "./camera/camera_preview_image";
+export type {
+  CameraConfiguration,
+  CameraSystemState,
+} from "./camera/camera_configuration";
+export {
+  getCameraPermissionStatus,
+  requestCameraPermission,
+  type CameraPermissionStatus,
+} from "./camera/camera_permissions";
+
+// Types
+export {
+  JobType,
+  jobTypeFromValue,
+  requiresDocument,
+  requiresSelfie,
+  type JobTypeName,
+} from "./core/models/job_type";
+export { FlowStep } from "./core/models/flow_step";
+export {
+  DocumentType,
+  type DocumentOrientation,
+  type GenericDocumentArgs,
+} from "./core/models/document_type";
+export {
+  DEFAULT_ACTIVATE_MANUAL_AFTER_MS,
+  DocumentCaptureMode,
+  type AutoCaptureWithManualFallbackArgs,
+} from "./core/models/document_capture_mode";
+export {
+  cancelled,
+  failure,
+  success,
+  type UseSmileIDResult,
+} from "./core/models/result";
+export type { ConfigOptions } from "./core/models/config";
+export { LogLevel } from "./core/models/network_config";
+export type {
+  CacheConfig,
+  Interceptor,
+  NetworkConfig,
+  NetworkInnerConfig,
+  NetworkLoggingConfig,
+  PartnerConfig,
+  RetryConfig,
+  TimeoutConfig,
+} from "./core/models/network_config";
+export type { AnalyzerRegistry, MLConfig } from "./core/models/ml_config";
+export type {
+  BiometricKYCParams,
+  ConsentInformation,
+  DocumentVerificationParams,
+  EnhancedDocumentVerificationParams,
+  EnhancedKYCParams,
+  Timestamp,
+  UserDetails,
+} from "./core/models/params";
+export type {
+  UseSmileIDAnalyticsEvent,
+  UseSmileIDAnalyticsEventType,
+} from "./presentation/flow/analytics/use_smile_id_analytics_event";
+export type { JobSubmissionResponse } from "./data/model/job_submission_response";
+
+// Token decoding — JWT auth token decoder and sdk_config types.
+// Partners who want to inspect the token before starting a flow can
+// call `decodeSmileIDToken` directly; the flow manager also calls it
+// internally at flow start.
+export {
+  type DecodedToken,
+  decodeSmileIDToken,
+} from "./data/util/use_smile_id_token_decoder";
+export { type SdkConfig, numSamplesOverride } from "./data/model/sdk_config";
+export {
+  type SdkConfigCapture,
+  resolveDimensions,
+  resolveJpegQuality,
+} from "./data/model/sdk_config_capture";
+export type { ImageDimensions } from "./data/model/image_dimensions";
+export {
+  SdkConfigSource,
+  type SdkConfigSourceValue,
+} from "./data/model/sdk_config_source";
+
+// Theme
+export {
+  defaultDarkTheme,
+  defaultLightTheme,
+  DEFAULT_FONT_FAMILY,
+  DM_SANS_FONT_NAMES,
+  resolveFontFamily,
+  typographyWithFontFamily,
+  type UseSmileIDColors,
+  type UseSmileIDFontWeight,
+  type UseSmileIDShapes,
+  type UseSmileIDSpacing,
+  type UseSmileIDTextStyle,
+  type UseSmileIDTheme,
+  type UseSmileIDTypography,
+} from "./presentation/theme/theme";
+export {
+  UseSmileIDThemeProvider,
+  useUseSmileIDTheme,
+  type UseSmileIDThemeProviderProps,
+} from "./presentation/theme/theme_context";
+export {
+  loadUseSmileIDFonts,
+  useUseSmileIDFonts,
+} from "./presentation/theme/use_use_smile_id_fonts";
+
+// Components (stubs — visual implementation pending).
+export {
+  UseSmileIDButton,
+  type UseSmileIDButtonProps,
+} from "./presentation/components/use_smile_id_button";
+export {
+  UseSmileIDBackButton,
+  type UseSmileIDBackButtonProps,
+} from "./presentation/components/use_smile_id_back_button";
+export {
+  UseSmileIDRoundedCheckbox,
+  type UseSmileIDRoundedCheckboxProps,
+} from "./presentation/components/use_smile_id_rounded_checkbox";
+export {
+  UseSmileIDAttribution,
+  type UseSmileIDAttributionProps,
+} from "./presentation/components/use_smile_id_attribution";
+export {
+  UseSmileIDPartnerIcon,
+  type UseSmileIDPartnerIconProps,
+} from "./presentation/components/use_smile_id_partner_icon";
+export { StatusIndicatorState } from "./presentation/components/status_indicator_state";
+export {
+  UseSmileIDStatusIndicator,
+  type UseSmileIDStatusIndicatorProps,
+} from "./presentation/components/use_smile_id_status_indicator";
+export {
+  UseSmileIDLoadingIndicator,
+  type UseSmileIDLoadingIndicatorProps,
+} from "./presentation/components/use_smile_id_loading_indicator";
+export {
+  UseSmileIDExpandableIcon,
+  type UseSmileIDExpandableIconProps,
+} from "./presentation/components/use_smile_id_expandable_icon";
+export {
+  UseSmileIDContentCard,
+  type UseSmileIDContentCardProps,
+} from "./presentation/components/use_smile_id_content_card";
+export {
+  FaceOvalDefaults,
+  computeFaceOvalGeometry,
+  type FaceOvalGeometry,
+} from "./presentation/components/face_oval_defaults";
+export {
+  UseSmileIDOvalBorderPalette,
+  type OvalBorderColorToken,
+} from "./presentation/components/use_smile_id_oval_border_palette";
+export { UseSmileIDMotion } from "./presentation/theme/use_smile_id_motion";
+export {
+  UseSmileIDFaceOverlay,
+  type UseSmileIDFaceOverlayProps,
+} from "./presentation/components/use_smile_id_face_overlay";
+export {
+  UseSmileIDFaceOvalImage,
+  type UseSmileIDFaceOvalImageProps,
+} from "./presentation/components/use_smile_id_face_oval_image";
+export {
+  UseSmileIDCapturedImageOval,
+  type UseSmileIDCapturedImageOvalProps,
+} from "./presentation/components/use_smile_id_captured_image_oval";
+export {
+  UseSmileIDCardSurface,
+  type UseSmileIDCardSurfaceProps,
+} from "./presentation/components/use_smile_id_card_surface";
+export {
+  computeScaledOvalGeometry,
+  type ScaledOvalGeometry,
+} from "./presentation/components/helpers/scaled_oval_geometry";
+export {
+  UseSmileIDProcessingCenterIndicator,
+  type UseSmileIDProcessingCenterIndicatorProps,
+} from "./presentation/components/use_smile_id_processing_center_indicator";
+export {
+  UseSmileIDDocumentOverlay,
+  type UseSmileIDDocumentOverlayProps,
+} from "./presentation/components/use_smile_id_document_overlay";
+export {
+  UseSmileIDFaceSilhouetteOverlay,
+  type UseSmileIDFaceSilhouetteOverlayProps,
+} from "./presentation/components/use_smile_id_face_silhouette_overlay";
+export {
+  UseSmileIDInstructionsHero,
+  type UseSmileIDInstructionsHeroProps,
+} from "./presentation/components/use_smile_id_instructions_hero";
+export {
+  UseSmileIDGuidelineThumbnail,
+  type UseSmileIDGuidelineThumbnailProps,
+} from "./presentation/components/use_smile_id_guideline_thumbnail";
+export {
+  type InstructionGuideline,
+  type GuidelineStatus,
+} from "./presentation/flow/model/instruction_guideline";
+export {
+  SELFIE_GUIDELINES,
+  SELFIE_HERO_ANIMATION,
+  ESS_HERO_ANIMATION,
+  type HeroAnimationSource,
+} from "./presentation/flow/model/instructions_defaults";
+export {
+  UseSmileIDConsentRow,
+  type UseSmileIDConsentRowProps,
+} from "./presentation/components/use_smile_id_consent_row";
+export {
+  UseSmileIDConfirmationButtons,
+  type UseSmileIDConfirmationButtonsProps,
+} from "./presentation/components/use_smile_id_confirmation_buttons";
+export {
+  UseSmileIDLoadingContent,
+  type UseSmileIDLoadingContentProps,
+} from "./presentation/components/use_smile_id_loading_content";
+export {
+  UseSmileIDSuccessContent,
+  type UseSmileIDSuccessContentProps,
+} from "./presentation/components/use_smile_id_success_content";
+export {
+  UseSmileIDFailedContent,
+  type UseSmileIDFailedContentProps,
+} from "./presentation/components/use_smile_id_failed_content";
+export {
+  UseSmileIDLearnMoreContent,
+  type UseSmileIDLearnMoreContentProps,
+} from "./presentation/components/use_smile_id_learn_more_content";
+export {
+  UseSmileIDEnhancedSmartSelfieFullAnimation,
+  type UseSmileIDEnhancedSmartSelfieFullAnimationProps,
+} from "./presentation/components/use_smile_id_enhanced_smart_selfie_full_animation";
+export {
+  UseSmileIDEnhancedSmartSelfieDirectionAnimation,
+  type UseSmileIDEnhancedSmartSelfieDirectionAnimationProps,
+} from "./presentation/components/use_smile_id_enhanced_smart_selfie_direction_animation";
+export {
+  EnhancedSmartSelfieAnimationFrames,
+  ENHANCED_SMART_SELFIE_TOTAL_FRAMES,
+  ENHANCED_SMART_SELFIE_FRAME_RATE,
+} from "./presentation/components/helpers/enhanced_smart_selfie_animation_frames";
+export {
+  UseSmileIDCaptureContent,
+  type UseSmileIDCaptureContentProps,
+  type UseSmileIDCaptureContentState,
+} from "./presentation/components/use_smile_id_capture_content";
+export {
+  UseSmileIDCaptureInstructionAnimation,
+  type UseSmileIDCaptureInstructionAnimationProps,
+} from "./presentation/components/use_smile_id_capture_instruction_animation";
+export {
+  captureInstructionAnimationSpec,
+  type CaptureInstructionAnimationSpec,
+} from "./presentation/components/helpers/capture_instruction_animation_spec";
+export {
+  mapCaptureUiState,
+  mapSelfieUiState,
+  mapDocumentUiState,
+  preCaptureUiState,
+  scannedUiState,
+  scannedDocumentUiState,
+  withEnhancedLivenessPolicy,
+  type UseSmileIDCaptureUiState,
+} from "./presentation/screen/helpers/capture_ui_state";
+export {
+  resolveFeedbackCopy,
+  selfieFeedbackKeyFor,
+  documentFeedbackKeyFor,
+} from "./presentation/screen/helpers/capture_screen_helpers";
+export { UseSmileIDFeedbackDebouncer } from "./presentation/screen/helpers/feedback_debouncer";
+
+// State — drives overlay rendering.
+export {
+  UseSmileIDOverlayState,
+  OVERLAY_STATE_COUNT,
+  isDirectional,
+} from "./presentation/state/use_smile_id_overlay_state";
+export {
+  HEAD_TURN_DIRECTIONS,
+  type HeadTurnDirection,
+} from "./core/models/head_turn_direction";
+
+// Screens (stubs — visual implementation pending)
+export {
+  UseSmileIDCaptureScreen,
+  type UseSmileIDCaptureScreenProps,
+} from "./presentation/screen/use_smile_id_capture_screen";
+export {
+  UseSmileIDConsentScreen,
+  type UseSmileIDConsentScreenProps,
+} from "./presentation/screen/use_smile_id_consent_screen";
+export {
+  UseSmileIDInstructionsScreen,
+  type UseSmileIDInstructionsScreenProps,
+} from "./presentation/screen/use_smile_id_instructions_screen";
+export {
+  UseSmileIDDocumentBackInstructions,
+  type UseSmileIDDocumentBackInstructionsProps,
+} from "./presentation/screen/use_smile_id_document_back_instructions";
+export {
+  UseSmileIDPermissionScreen,
+  type UseSmileIDPermissionScreenProps,
+} from "./presentation/screen/use_smile_id_permission_screen";
+export {
+  UseSmileIDPreviewScreen,
+  type UseSmileIDPreviewScreenProps,
+} from "./presentation/screen/use_smile_id_preview_screen";
+export {
+  UseSmileIDProcessingScreen,
+  type ProcessingState,
+  type UseSmileIDProcessingScreenProps,
+} from "./presentation/screen/use_smile_id_processing_screen";
+
+// Presentation utilities — opt-in components for partners building
+// custom capture surfaces. The canonical capture screen wires
+// these internally.
+export { ForceMaxBrightness } from "./presentation/utils/force_max_brightness";
+export type { ForceMaxBrightnessProps } from "./presentation/utils/force_max_brightness";

package/src/l10n/__tests__/use_smile_id_localizations.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it } from "vitest";
+import { UseSmileIDLocalizations } from "../use_smile_id_localizations";
+import { CANONICAL_KEY_COUNT, enStrings } from "../strings_en";
+
+describe("strings_en — canonical key set", () => {
+  it("matches the documented canonical key count", () => {
+    // Concrete scenario: we silently drop a key during a refactor —
+    // RN renders the English fallback but partner overrides break
+    // for the missing key. Pin the count so any change requires
+    // bumping `CANONICAL_KEY_COUNT`.
+    expect(Object.keys(enStrings).length).toBe(CANONICAL_KEY_COUNT);
+  });
+
+  it("every key starts with the `si_` prefix", () => {
+    for (const key of Object.keys(enStrings)) {
+      expect(key).toMatch(/^si_/);
+    }
+  });
+
+  it("parameterized strings use named tokens, not positional `%1$s`", () => {
+    // The convention is named-token interpolation (`{partnerName}`).
+    // A regression that re-introduces positional tokens here would
+    // break translations that rely on the named-token contract.
+    for (const value of Object.values(enStrings)) {
+      expect(value).not.toMatch(/%\d+\$[s@]/);
+    }
+  });
+});
+
+describe("UseSmileIDLocalizations", () => {
+  it("returns English defaults when no overrides are passed", () => {
+    const loc = new UseSmileIDLocalizations();
+    expect(loc.siLabelContinue).toBe("Continue");
+    expect(loc.siInstructionsTitlePrefix).toBe("Get ready to capture your");
+    expect(loc.siInstructionsEmphasisSelfie).toBe("selfie");
+    expect(loc.siCaptureSmile).toBe("Please smile…");
+  });
+
+  it("uses overrides when present and falls back per-key when missing", () => {
+    // Concrete scenario: a partner ships only the consent strings
+    // translated, leaving capture-screen feedback at English. Their
+    // partial overrides map should NOT force the rest of the SDK
+    // into a "no fallback found" state; per-key fallback is the
+    // contract.
+    const loc = new UseSmileIDLocalizations({
+      si_consent_allow: "Autoriser",
+      si_consent_deny: "Refuser",
+    });
+    expect(loc.siConsentAllow).toBe("Autoriser");
+    expect(loc.siConsentDeny).toBe("Refuser");
+    expect(loc.siCaptureTooClose).toBe("Move your device away from your face");
+    expect(loc.siLabelContinue).toBe("Continue");
+  });
+
+  it("renders {name} placeholders via _t — siConsentTitle parameterized", () => {
+    const loc = new UseSmileIDLocalizations();
+    expect(loc.siConsentTitle("Acme")).toBe(
+      "Acme would like to verify your identity using Smile ID.",
+    );
+  });
+
+  it("renders multiple placeholder occurrences (replaceAll semantics)", () => {
+    // Concrete scenario: a future translation duplicates the
+    // partner-name token (e.g. greeting + footer). The previous
+    // implementation used `String.replace` (single replacement) and
+    // would only swap the first. The current `split/join` does all
+    // occurrences — pin the contract.
+    const loc = new UseSmileIDLocalizations({
+      si_consent_title: "{partnerName} hi {partnerName}",
+    });
+    expect(loc.siConsentTitle("Acme")).toBe("Acme hi Acme");
+  });
+
+  it("uses partner override for parameterized partner-link key", () => {
+    // Partner-link key uses the `{partnerName}` named-token
+    // interpolation contract — confirm the override path renders
+    // correctly with a translated string.
+    const loc = new UseSmileIDLocalizations({
+      si_consent_learn_more_privacy_partner_link: "Politique {partnerName}",
+    });
+    expect(loc.siConsentLearnMorePrivacyPartnerLink("Acme")).toBe(
+      "Politique Acme",
+    );
+  });
+
+  it("renders the document flip title with the {id_type} token", () => {
+    const loc = new UseSmileIDLocalizations();
+    expect(loc.siDocumentFlipTitle("Green Book")).toBe("Flip your Green Book");
+    expect(loc.siDocumentCaptureBack).toBe("Capture Back of ID");
+    expect(loc.siDocumentSkipBack).toBe("Skip");
+    expect(loc.siDocumentGuidelineGood).toBe("Good");
+    expect(loc.siDocumentGuidelineNotReflective).toBe("Not reflective");
+  });
+
+  describe("fromOverrides static helper", () => {
+    it("strips ARB metadata keys (`@@locale`, `@key`)", () => {
+      // ARB files put `@@locale: "fr"` and per-key
+      // `@key: { description: ..., placeholders: ... }` metadata at
+      // the top level. Partners should be able to feed an ARB JSON
+      // straight into us without preprocessing.
+      const loc = UseSmileIDLocalizations.fromOverrides({
+        "@@locale": "fr",
+        "@si_consent_allow": { description: "Allow button label" },
+        si_consent_allow: "Autoriser",
+      });
+      expect(loc.siConsentAllow).toBe("Autoriser");
+    });
+
+    it("drops non-string values defensively", () => {
+      // Concrete scenario: a partner accidentally ships a JSON file
+      // with `si_processing_continue: 123` (number). Without this
+      // filter, our `_overrides` map would carry a `number` value
+      // and `_s(...)` would happily return it — TS wouldn't catch
+      // because we type as `Record<string, unknown>` at the
+      // boundary. Filter at parse time so the runtime contract
+      // (`_s` returns a string) holds.
+      const loc = UseSmileIDLocalizations.fromOverrides({
+        si_consent_allow: "Autoriser",
+        si_processing_continue: 123,
+        si_consent_deny: null,
+      });
+      expect(loc.siConsentAllow).toBe("Autoriser");
+      expect(loc.siProcessingContinue).toBe("Continue"); // English fallback
+      expect(loc.siConsentDeny).toBe("Deny"); // English fallback
+    });
+  });
+});