react-native-ensys-camera-x 1.0.7

package/src/types.ts

@@ -0,0 +1,946 @@
+import type {
+  CameraLanguageProvider,
+  CameraTranslationBundles,
+  CameraTranslationMap,
+} from './localization';
+// Type-only (fully erased at build time), so this does not create a runtime
+// import cycle with `iconConfig.tsx`, which imports the icon types below.
+import type { CameraIconsConfig } from './iconConfig';
+
+export type CameraPickerOptions = {
+  mediaTypes?: 'all' | 'photo' | 'video';
+  /** Maximum selectable items. 0 or omitted = unlimited. */
+  selectionLimit?: number;
+  initialCamera?: 'back' | 'front';
+  enableVideo?: boolean;
+  enableVideoNotes?: boolean;
+  enableFilter?: boolean;
+  /**
+   * Press and hold the shutter to record video, release to stop (WhatsApp-style). Works in both
+   * photo and video mode; a plain tap keeps its usual meaning (photo, or start/stop in video
+   * mode). Ignored when video is unavailable (`enableVideo: false` or `mediaTypes: 'photo'`).
+   *
+   * @default true
+   */
+  enableHoldToRecord?: boolean;
+  /**
+   * How long (ms) the shutter must be held before recording starts. Omit or pass 0 to use the
+   * platform long-press timeout (500 ms on most devices), which matches every other
+   * press-and-hold on the phone. Clamped to 120–2000 ms.
+   */
+  holdToRecordDelayMs?: number;
+  /**
+   * Hold-recordings shorter than this (ms) are discarded instead of published — releasing a
+   * moment after the hold threshold otherwise produces a useless fragment. Pass 0 to keep every
+   * clip. Clamped to 0–5000 ms.
+   *
+   * @default 1000
+   */
+  minRecordDurationMs?: number;
+  /**
+   * Allow sliding up from the shutter onto the lock rail to keep recording hands-free after the
+   * finger is lifted. Requires {@link enableHoldToRecord}.
+   *
+   * @default true
+   */
+  enableRecordLock?: boolean;
+  /**
+   * Allow sliding sideways from the shutter onto the cancel pill to abort a hold-recording and
+   * discard the clip. Requires {@link enableHoldToRecord}.
+   *
+   * @default true
+   */
+  enableRecordCancel?: boolean;
+};
+
+/**
+ * Options for the document and audio pickers (Storage Access Framework on Android).
+ */
+export type FilePickerOptions = {
+  /** Maximum selectable items. 0 or omitted = unlimited (enables multi-select). */
+  selectionLimit?: number;
+  /**
+   * MIME types to accept, e.g. `['application/pdf']` or `['audio/mpeg']`. Omit to use the
+   * picker's sensible defaults (common document formats for the document picker, `audio/*`
+   * for the audio picker).
+   */
+  mimeTypes?: string[];
+};
+
+/** One photo/video handed to {@link openMediaEditor}. */
+export type MediaEditorItem = {
+  /** content:// or file:// uri of the media to edit. Required. */
+  uri: string;
+  /**
+   * Media kind. Omit to let the native side type the uri from its content provider — pass it
+   * explicitly when the caller already knows (e.g. straight from a picker result).
+   */
+  type?: 'photo' | 'video';
+  /** Display name, used when the provider doesn't expose one. */
+  fileName?: string;
+  /** MIME type, used when the content resolver can't type the uri. */
+  mimeType?: string;
+};
+
+/**
+ * Options for {@link openMediaEditor} — opening EXISTING photos/videos (typically ones the user
+ * just picked from the device gallery) on the camera's own preview/editor screens.
+ *
+ * Pass a single item inline (`uri`, plus the optional hints) or several through {@link items}, in
+ * the order they were picked. One item opens the single-asset image/video editor; several open the
+ * multi-media Add More + Send preview — the same rule the capture flow follows.
+ */
+export type MediaEditorOptions =
+  | (MediaEditorItem & {
+      items?: never;
+      /** Show the filter tool in the editor. @default true */
+      enableFilter?: boolean;
+    })
+  | {
+      /** One or more items, in pick order. */
+      items: MediaEditorItem[];
+      /** Show the filter tool in the editor. @default true */
+      enableFilter?: boolean;
+    };
+
+/**
+ * Options for {@link openGalleryEditor} — the device-gallery pick that flows straight into the
+ * editor. Everything except the picker itself is forwarded to {@link openMediaEditor}.
+ */
+export type GalleryEditorOptions = {
+  /** Show the filter tool in the editor. @default true */
+  enableFilter?: boolean;
+};
+
+export type CameraAsset = {
+  id: string;
+  uri: string;
+  type: 'photo' | 'video' | 'document' | 'audio';
+  fileName?: string;
+  mimeType?: string;
+  caption?: string;
+  width?: number;
+  height?: number;
+  duration?: number;
+  size?: number;
+  dateTaken?: number;
+  location?: {
+    latitude?: number;
+    longitude?: number;
+  };
+  // Cache-related metadata (populated when native code caches a media file)
+  cachePath?: string;
+  documentUri?: string;
+  isCached?: boolean;
+  cacheCreatedAt?: number;
+  cacheLastModified?: number;
+  originalUri?: string;
+  // Storage workflow metadata (populated by the media storage service)
+  storageLocation?: MediaStorageLocation;
+  storageStatus?: MediaStorageStatus;
+  publishedAt?: number;
+  // Edit tracking properties
+  filteredFrom?: string;
+  croppedFrom?: string;
+  rotatedFrom?: string;
+  needsThumbnail?: boolean;
+  // Aspect ratio for consistent WYSIWYG preview
+  // Used to ensure all captures display with the same aspect ratio as the camera preview
+  previewAspectRatio?: number;
+  // For videos: URI of the user-selected cover/poster frame (chosen in the editor before sending).
+  coverUri?: string;
+  // Exact container dimensions (in pixels) used for the camera preview at capture time.
+  // Used by the editor to reproduce the identical framing without recalculation drift.
+  captureContainerWidth?: number;
+  captureContainerHeight?: number;
+  /**
+   * True when {@link size} is a DISPLAY convention rather than the exact bytes on disk. Set by the
+   * native editor for a compressed video: `size` then holds the proportional figure the compression
+   * dropdown and completion toast quote (`original × (1 − percent/100)`), not the produced file's
+   * own bytes. {@link refreshAssetMetadata} keeps `size` as-is for such a clip instead of re-statting
+   * the file, so the preview / Info panel reads as the proportion the user picked. Everything else
+   * (originals, muted/trimmed clips, stills, gallery imports) leaves this unset and re-stats normally.
+   */
+  sizeIsDisplayEstimate?: boolean;
+};
+
+export type CameraPickerResult = {
+  cancelled: boolean;
+  assets: CameraAsset[];
+};
+
+export type ImageCropOptions = {
+  width?: number;
+  height?: number;
+  x?: number;
+  y?: number;
+};
+
+export type FilterType = 'none' | 'grayscale' | 'sepia' | 'vintage' | 'blur';
+
+export type FlashMode = 'off' | 'on' | 'auto' | 'torch';
+
+export type FaceEffect = 'none' | 'dog' | 'cat' | 'glasses' | 'hat';
+
+export type CameraTheme = 'default' | 'dark' | 'light' | 'minimal';
+
+export type CameraThemePreset = CameraTheme;
+
+export type CameraThemePalette = {
+  background: string;
+  surface: string;
+  surfaceMuted: string;
+  surfaceElevated: string;
+  primary: string;
+  primaryMuted: string;
+  primaryContrast: string;
+  text: string;
+  textMuted: string;
+  textSecondary: string;
+  border: string;
+  borderStrong: string;
+  overlay: string;
+  overlayStrong: string;
+  accent: string;
+  success: string;
+  error: string;
+  warning: string;
+};
+
+/**
+ * Named font weights. Every text style in the plugin reads its `fontWeight`
+ * from these tokens — components never hardcode a weight string.
+ */
+export type CameraFontWeight =
+  | 'normal'
+  | 'bold'
+  | '100'
+  | '200'
+  | '300'
+  | '400'
+  | '500'
+  | '600'
+  | '700'
+  | '800'
+  | '900';
+
+export type CameraThemeTypography = {
+  fontFamily: string;
+  headingSize: number;
+  bodySize: number;
+  captionSize: number;
+  buttonSize: number;
+  /** Named font weights — the single source of truth for `fontWeight` styles. */
+  fontWeights: {
+    regular: CameraFontWeight;
+    medium: CameraFontWeight;
+    semibold: CameraFontWeight;
+    bold: CameraFontWeight;
+  };
+};
+
+export type CameraThemeSpacing = {
+  xs: number;
+  sm: number;
+  md: number;
+  lg: number;
+  xl: number;
+  xxl: number;
+};
+
+export type CameraThemeBorderRadius = {
+  sm: number;
+  md: number;
+  lg: number;
+  xl: number;
+  pill: number;
+  circle: number;
+};
+
+export type CameraThemeShadow = {
+  color: string;
+  opacity: number;
+  radius: number;
+  offset: {
+    width: number;
+    height: number;
+  };
+};
+
+export type CameraThemeCameraPreviewStyles = {
+  // ── Colors ───────────────────────────────────────────────────────────────
+  background: string;
+  overlay: string;
+  placeholderText: string;
+  loadingText: string;
+  controlButtonBackground: string;
+  controlButtonText: string;
+  captureButtonBackground: string;
+  captureButtonInnerBorder: string;
+  closeButtonBackground: string;
+  closeButtonText: string;
+  modeIndicatorBackground: string;
+  modeIndicatorText: string;
+  // ── Layout metrics (dp unless noted) ─────────────────────────────────────
+  controlButtonSize: number;
+  controlIconSize: number;
+  controlButtonTextSize: number;
+  captureButtonSize: number;
+  captureButtonInnerSize: number;
+  captureButtonBorderWidth: number;
+  closeButtonSize: number;
+  closeIconSize: number;
+  closeButtonTextSize: number;
+  modeIndicatorRadius: number;
+  modeIndicatorPaddingVertical: number;
+  modeIndicatorPaddingHorizontal: number;
+  modeIndicatorIconSize: number;
+  modeIndicatorTextSize: number;
+  controlsBottomInset: number;
+  controlsPaddingHorizontal: number;
+  topInset: number;
+  sideInset: number;
+  placeholderTextSize: number;
+  loadingTextSize: number;
+  disabledOpacity: number;
+};
+
+export type CameraThemeResponsivePreviewStyles = {
+  background: string;
+  borderRadius: number;
+  /** Fraction of screen width used for the preview container (stock 0.96). */
+  widthRatio: number;
+  /** Maximum preview width in logical pixels (stock 720). */
+  maxWidth: number;
+  /** Maximum fraction of screen height the preview may occupy (stock 0.92). */
+  maxHeightRatio: number;
+};
+
+export type CameraThemeAudioPlayerStyles = {
+  // ── Colors ───────────────────────────────────────────────────────────────
+  containerBackground: string;
+  borderColor: string;
+  borderRadius: number;
+  shadow: CameraThemeShadow;
+  progressTrackBackground: string;
+  progressFillBackground: string;
+  iconButtonBackground: string;
+  iconColor: string;
+  titleColor: string;
+  textColor: string;
+  // ── Layout metrics (dp unless noted) ─────────────────────────────────────
+  containerBorderWidth: number;
+  containerElevation: number;
+  progressTrackHeight: number;
+  contentPaddingHorizontal: number;
+  contentPaddingVertical: number;
+  iconButtonSize: number;
+  iconButtonRadius: number;
+  playIconSize: number;
+  closeIconSize: number;
+  titleFontSize: number;
+  titleFontWeight: CameraFontWeight;
+  titleMarginHorizontal: number;
+  iconTextSize: number;
+  iconTextWeight: CameraFontWeight;
+  /** Pressable opacity when the mini-player is touched. */
+  activeOpacity: number;
+};
+
+export type CameraThemeComponentStyles = {
+  cameraPreview: CameraThemeCameraPreviewStyles;
+  responsivePreviewContainer: CameraThemeResponsivePreviewStyles;
+  audioPlayer: CameraThemeAudioPlayerStyles;
+};
+
+export type CameraThemeComponentStyle =
+  | CameraThemeCameraPreviewStyles
+  | CameraThemeResponsivePreviewStyles
+  | CameraThemeAudioPlayerStyles;
+
+export type CameraThemeConfig = {
+  name: CameraThemePreset;
+  colors: CameraThemePalette;
+  typography: CameraThemeTypography;
+  spacing: CameraThemeSpacing;
+  borderRadius: CameraThemeBorderRadius;
+  shadows: {
+    small: CameraThemeShadow;
+    medium: CameraThemeShadow;
+  };
+  components: CameraThemeComponentStyles;
+};
+
+export type CameraThemeInput = CameraThemePreset | Partial<CameraThemeConfig>;
+
+// ===== White-label configuration types =====
+
+/**
+ * NATIVE icon layer (low-level).
+ *
+ * The types in this section ({@link CameraIconName} / {@link CameraIconStyle} /
+ * {@link CameraIconConfig}) configure the icons rendered by the NATIVE camera
+ * Activity, which is Kotlin UI and physically cannot render React components.
+ * They describe Android vector drawables or inline SVG (per-icon tint / size,
+ * an optional host `resourceName`, and Android resource-merging).
+ *
+ * This is a SEPARATE, independent layer from the RN React-component icon
+ * registry in `src/icons.tsx` (`CameraIconKey` / `IconComponent` /
+ * `CameraIconRegistryConfig`), which renders the icons used by the JS/TS UI
+ * surface. The two never share state and are intentionally named to avoid
+ * collision — do not conflate `CameraIconName` (native drawables) with
+ * `CameraIconKey` (RN registry keys).
+ *
+ * HOST APPS SHOULD NOT NEED EITHER OF THEM: `src/iconConfig.tsx` puts one
+ * catalog of unique `CameraIconId` keys in front of both layers, and
+ * `CameraPluginConfig.customIcons` / `setCameraIcons()` is the single documented
+ * way to replace an icon. The types here remain public for the low-level escape
+ * hatch and for backwards compatibility.
+ *
+ * Canonical names of every native icon the plugin renders. Each maps 1:1 to a
+ * vector drawable in the plugin's Android `res/drawable` folder (`ic_close`,
+ * `ic_flip`, …) — except `selectionCheck`, which draws `ic_check`. Host apps can
+ * replace any of them via Android resource merging (ship a same-named drawable)
+ * and/or tint & size them from JS via {@link CameraIconConfig}.
+ */
+export type CameraIconName =
+  | 'close'
+  | 'back'
+  | 'done'
+  | 'flip'
+  | 'flash_on'
+  | 'flash_off'
+  | 'flash_auto'
+  | 'gallery'
+  | 'photo_mode'
+  | 'video_mode'
+  | 'video_note'
+  | 'send'
+  | 'crop'
+  | 'rotate'
+  | 'aspect_ratio'
+  | 'filter'
+  | 'sticker'
+  | 'emoji'
+  | 'gif'
+  | 'text'
+  | 'text_bg'
+  | 'text_align_left'
+  | 'text_align_center'
+  | 'text_align_right'
+  | 'marker'
+  | 'brush_thin'
+  | 'brush_medium'
+  | 'brush_thick'
+  | 'undo'
+  | 'redo'
+  | 'clear_drawing'
+  | 'overlay_close'
+  | 'overlay_resize'
+  | 'play'
+  | 'pause'
+  | 'lock'
+  | 'lock_open'
+  | 'chevron_up'
+  | 'chevron_down'
+  | 'more_vert'
+  | 'delete'
+  | 'selectionCheck'
+  | 'document'
+  | 'audio'
+  | 'trim'
+  | 'cover'
+  | 'volume_on'
+  | 'volume_off'
+  | 'download'
+  | 'share'
+  | 'stat_upload';
+
+/** Per-icon appearance override. Omitted fields keep the built-in defaults. */
+export type CameraIconStyle = {
+  /** Tint color applied to the vector drawable (any CSS color string). */
+  tintColor?: string;
+  /** Rendered size in dp (icons are square). */
+  size?: number;
+  /**
+   * Name of a drawable resource in the HOST app to render instead of the
+   * built-in icon (resolved with `Resources.getIdentifier`; falls back to the
+   * built-in drawable when not found). Prefer plain resource-merging (shipping
+   * a drawable with the plugin's own name) — this is the escape hatch for apps
+   * that cannot shadow resource names.
+   */
+  resourceName?: string;
+  /** Inline SVG markup parsed by the native Android icon renderer. */
+  svg?: string;
+};
+
+/**
+ * Icon configuration: a global tint applied to every icon plus per-icon
+ * overrides. Defaults reproduce the current build exactly (white icons at
+ * their existing sizes).
+ */
+export type CameraIconConfig = {
+  /** Tint applied to all icons unless overridden per icon. */
+  tintColor?: string;
+  /** Per-icon overrides keyed by {@link CameraIconName}. */
+  overrides?: Partial<Record<CameraIconName, CameraIconStyle>>;
+};
+
+/**
+ * Durations (ms) of every animation the native UI runs. Defaults equal the
+ * values currently hardcoded in the native views, so leaving this out changes
+ * nothing.
+ */
+export type CameraAnimationConfig = {
+  /** Master switch — `true` sets every duration to 0 (reduced motion). */
+  disableAnimations?: boolean;
+  /** Shutter press-down/up scale feedback (default 80). */
+  shutterPress?: number;
+  /** Mode/tab and control fade transitions in the camera screen (default 180). */
+  controlsFade?: number;
+  /** Gallery strip slide in/out (default 260 in / 220 out). */
+  stripSlideIn?: number;
+  stripSlideOut?: number;
+  /** Selection badge / remove button fades in grids (default 150). */
+  selectionFade?: number;
+  /** Video poster crossfade when playback starts (default 120). */
+  posterFade?: number;
+  /** Play/pause glyph flash on tap (default 200 show, 600 fade after 400 delay). */
+  playPauseFlash?: number;
+  playPauseFadeOut?: number;
+  playPauseFadeDelay?: number;
+  /** Editor overlay/panel fades (default 250 in / 200 out). */
+  overlayFadeIn?: number;
+  overlayFadeOut?: number;
+  /** Editor sheet/panel slide animations (default 350 / 300). */
+  panelSlideIn?: number;
+  panelSlideOut?: number;
+  /** Toolbar icon state transitions in the editor (default 180). */
+  editorIconFade?: number;
+  /** Generic small fades (thumb press states etc., default 150). */
+  quickFade?: number;
+};
+
+/**
+ * Structural metrics (dp unless noted) of the native UI. Defaults equal the
+ * currently hardcoded layout values.
+ */
+export type CameraDimensionConfig = {
+  /** Camera-screen circular control button diameter. */
+  controlButtonSize?: number;
+  /** Icon size inside camera-screen control buttons. */
+  controlIconSize?: number;
+  /** Shutter button outer diameter. */
+  shutterSize?: number;
+  /** Bottom mode-tab bar height. */
+  modeTabHeight?: number;
+  /** Recent-media strip thumbnail edge length. */
+  stripThumbnailSize?: number;
+  /** Gallery grid column count. */
+  galleryColumns?: number;
+  /** Gallery grid cell spacing. */
+  gridSpacing?: number;
+  /** Editor toolbar height. */
+  editorToolbarHeight?: number;
+  /** Editor toolbar icon size. */
+  editorIconSize?: number;
+  /** Send button diameter in the editor. */
+  sendButtonSize?: number;
+  /** Selected-media tray thumbnail edge length in the editor. */
+  trayThumbnailSize?: number;
+};
+
+/**
+ * Upload notification appearance/wording. Defaults equal the current
+ * hardcoded channel ids, names, and texts, so omitting this changes nothing.
+ * Channel ids are only applied on first creation (Android caches channels).
+ */
+export type UploadNotificationConfig = {
+  /** Progress channel id (default `UploadServiceChannel`). */
+  progressChannelId?: string;
+  /** Progress channel user-visible name. */
+  progressChannelName?: string;
+  /** Result channel id (default `UploadResultChannel`). */
+  resultChannelId?: string;
+  /** Result channel user-visible name. */
+  resultChannelName?: string;
+  /** Accent color for the notification (any CSS color string). */
+  accentColor?: string;
+  /**
+   * Host-app drawable name for the small status icon (must be a plain
+   * monochrome vector — adaptive/launcher icons are silently dropped by
+   * Android). Falls back to the built-in `ic_stat_upload`.
+   */
+  smallIconResourceName?: string;
+  /** Title while uploading; `{0}` = current file index, `{1}` = total. */
+  progressTitle?: string;
+  /** Title when every file uploaded successfully. */
+  successTitle?: string;
+  /** Body when every file uploaded successfully; `{0}` = file count. */
+  successText?: string;
+  /** Title when one or more uploads failed. */
+  failureTitle?: string;
+  /** Body when one or more uploads failed; `{0}` = failed count. */
+  failureText?: string;
+};
+
+/**
+ * GIF picker configuration for the in-editor "Add GIF" tool.
+ *
+ * The API key is delivered here (via `setCameraConfig`) rather than as a
+ * per-launch option so the secret is set once at app startup and never rides
+ * in Intent extras. When `apiKey` is omitted the "Add GIF" button still shows
+ * but the picker renders a "not configured" state instead of calling out.
+ */
+export type GifPickerConfig = {
+  /**
+   * Which GIF service to use. `giphy` (default) or `tenor`. GIPHY is the
+   * default because Google has announced the Tenor API is being discontinued.
+   */
+  provider?: 'giphy' | 'tenor';
+  /** API key for the selected provider. Required for the picker to fetch GIFs. */
+  apiKey?: string;
+};
+
+/**
+ * The full white-label configuration. Every section is optional and
+ * deep-merged over built-in defaults that reproduce the current UI exactly.
+ */
+export type CameraPluginConfig = {
+  theme?: CameraThemeInput;
+  /**
+   * THE centralized language setting: the host app's currently active language
+   * as a BCP-47 tag — `'en'`, `'fr'`, `'pt-BR'`, `'zh-Hans'`, `'ar'` — or a
+   * {@link CameraLanguageProvider} that reports it live.
+   *
+   * The plugin has no language selector of its own; it displays whatever the
+   * host is displaying. Set this to the host's active language and pass the
+   * matching text through {@link CameraPluginConfig.translations} (or a
+   * translate callback via `setCameraLocalization`). Right-to-left layout is
+   * derived from the tag, so Arabic and Persian need no extra flag.
+   *
+   * Pass a provider — `{ get, subscribe }` — to configure this **once**: the
+   * plugin then follows every later host language change on its own, across both
+   * the React Native screens and the native camera. Pass a plain tag instead and
+   * call `configureCameraPlugin({ language })` again (or the lighter
+   * `setCameraLanguage(tag)`) on each switch. Either way open plugin screens and
+   * the native camera update immediately, with no restart.
+   *
+   * ```ts
+   * configureCameraPlugin({
+   *   translations: myBundles,
+   *   language: {
+   *     get: () => i18n.language,
+   *     subscribe: (onChange) => {
+   *       i18n.on('languageChanged', onChange);
+   *       return () => i18n.off('languageChanged', onChange);
+   *     },
+   *   },
+   * });
+   * ```
+   */
+  language?: string | CameraLanguageProvider;
+  /**
+   * Translations for every language the host supports, keyed by language tag:
+   * `{ fr: { send: 'Envoyer' }, ar: { send: 'إرسال' } }`.
+   *
+   * Register these once; switching {@link CameraPluginConfig.language} then
+   * picks the right one. Any key a language is missing falls back to
+   * {@link CameraPluginConfig.fallbackLanguage}, and then to English.
+   */
+  translations?: CameraTranslationBundles;
+  /** Language used to fill gaps in the active one. Defaults to `'en'`. */
+  fallbackLanguage?: string;
+  /**
+   * Translation overrides for the active language only. Wins over everything in
+   * {@link CameraPluginConfig.translations}.
+   */
+  strings?: CameraTranslationMap;
+  /**
+   * Force right-to-left layout for native screens.
+   *
+   * Normally leave this unset: direction follows
+   * {@link CameraPluginConfig.language} automatically.
+   */
+  rtl?: boolean;
+  /**
+   * THE centralized icon configuration: icon id → your replacement icon.
+   *
+   * This is the section to customize icons with — one flat map of unique keys
+   * that covers both the React Native components and the native camera screen.
+   * Any id you leave out keeps the icon the plugin ships. See
+   * `CAMERA_ICON_CATALOG` for every available key.
+   */
+  customIcons?: CameraIconsConfig;
+  /**
+   * Low-level native drawable settings (global tint plus per-drawable
+   * overrides). Prefer {@link CameraPluginConfig.customIcons}, which covers the
+   * same ground with unique keys and also reaches the React Native surface;
+   * per-icon values set there win over anything set here.
+   */
+  icons?: CameraIconConfig;
+  animations?: CameraAnimationConfig;
+  dimensions?: CameraDimensionConfig;
+  notifications?: UploadNotificationConfig;
+  /** GIF picker provider + API key for the editor's "Add GIF" tool. */
+  gif?: GifPickerConfig;
+};
+
+export type MediaMetadata = {
+  uri: string;
+  type: 'photo' | 'video';
+  width?: number;
+  height?: number;
+  duration?: number;
+  size?: number;
+  dateTaken?: number;
+  fileName?: string;
+  mimeType?: string;
+  location?: {
+    latitude?: number;
+    longitude?: number;
+  };
+  caption?: string;
+};
+
+export type PerformanceMetrics = {
+  operation: string;
+  durationMs: number;
+  memoryUsageMb?: number;
+  timestamp: number;
+};
+
+// ===== Audio Recording Types =====
+
+/**
+ * Options for starting an audio recording via native MediaRecorder.
+ * All fields are optional; sensible defaults are used server-side.
+ */
+export type AudioRecordingOptions = {
+  /**
+   * Output container format.
+   * - `'mpeg4'` (default) — AAC in MP4 container (.m4a)
+   * - `'aac_adts'` — raw AAC stream (.aac)
+   * - `'amr_nb'` — AMR narrow-band (.amr)
+   * - `'amr_wb'` — AMR wide-band (.amr)
+   * - `'three_gpp'` — AMR/WB in 3GPP container (.3gp)
+   */
+  outputFormat?: 'mpeg4' | 'aac_adts' | 'amr_nb' | 'amr_wb' | 'three_gpp';
+  /**
+   * Audio encoder.
+   * - `'aac'` (default) — Advanced Audio Coding
+   * - `'amr_nb'` — AMR narrow-band
+   * - `'amr_wb'` — AMR wide-band
+   * - `'he_aac'` — High-Efficiency AAC
+   */
+  audioEncoder?: 'aac' | 'amr_nb' | 'amr_wb' | 'he_aac';
+  /**
+   * Audio source for the recording.
+   * - `'mic'` (default) — Built-in microphone
+   * - `'camcorder'` — Same as camcorder (usually same as mic)
+   * - `'voice_recognition'` — Optimised for speech recognition
+   * - `'voice_communication'` — Optimised for VoIP
+   */
+  audioSource?: 'mic' | 'camcorder' | 'voice_recognition' | 'voice_communication';
+  /** Encoding bitrate in bits per second (default 128000). */
+  bitRate?: number;
+  /** Sampling rate in Hz (default 44100). */
+  sampleRate?: number;
+  /**
+   * Custom output file name (without directory). If omitted, a timestamp-based
+   * name like `"recording_1234567890.m4a"` is auto-generated.
+   */
+  fileName?: string;
+  /**
+   * Interval in milliseconds between amplitude callbacks.
+   * 0 (default) = disabled. When >0, the native side emits `onAudioAmplitude`
+   * DeviceEvent events at this interval.
+   */
+  meteringIntervalMs?: number;
+};
+
+/**
+ * Result returned from [startAudioRecording] on success.
+ */
+export type AudioRecordingResult = {
+  /** Absolute file path to the recording on disk. */
+  filePath: string;
+  /** MIME type of the recorded file (e.g. `"audio/mp4"`). */
+  mimeType: string;
+};
+
+/**
+ * Extended result returned from [stopAudioRecording].
+ */
+export type AudioRecordingStopResult = AudioRecordingResult & {
+  /** Effective recording duration in milliseconds (excluding pauses). */
+  durationMs: number;
+  /** Size of the final audio file in bytes. */
+  fileSizeBytes: number;
+};
+
+/**
+ * Snapshot of the recorder's state, returned by [getAudioRecordingState].
+ */
+export type AudioRecordingState = {
+  /** Current state: `'idle'`, `'recording'`, `'paused'`, or `'error'`. */
+  state: 'idle' | 'recording' | 'paused' | 'error';
+  /** Absolute path to the current output file (empty string when idle). */
+  filePath: string;
+  /** Elapsed recording time in milliseconds (excluding pauses). */
+  durationMs: number;
+  /** Whether pause/resume is supported on this device (API 24+). */
+  isPauseSupported: boolean;
+};
+
+// ===== Media Storage Types =====
+
+/**
+ * Storage locations for media files
+ */
+export type MediaStorageLocation = 'cache' | 'document' | 'gallery';
+
+/**
+ * Media storage status
+ */
+export type MediaStorageStatus =
+  | 'cached'
+  | 'moved'
+  | 'published'
+  | 'pending'
+  | 'error';
+
+/**
+ * Extended metadata for stored media
+ */
+export type StoredMediaMetadata = MediaMetadata & {
+  id: string;
+  storageLocation: MediaStorageLocation;
+  storageStatus: MediaStorageStatus;
+  cacheCreatedAt: number;
+  cacheLastModified: number;
+  publishedAt?: number;
+  documentUri?: string;
+  cachePath?: string;
+  originalUri?: string;
+  fileHash?: string;
+  isDuplicate?: boolean;
+  duplicateOf?: string;
+  isEdited: boolean;
+  edits?: {
+    cropped?: boolean;
+    filtered?: boolean;
+    rotated?: boolean;
+    degree?: number;
+  };
+};
+
+/**
+ * Media storage configuration
+ */
+export type MediaStorageConfig = {
+  maxCacheSizeMB: number;
+  autoCleanupEnabled: boolean;
+  autoCleanupIntervalMs: number;
+  duplicateDetection: boolean;
+  persistMetadata: boolean;
+  compressionQuality: number; // 0-100
+};
+
+/**
+ * Extra identity hints for {@link secureDeleteMedia}.
+ *
+ * All optional, but `assetId` should be supplied whenever it is known: derived
+ * copies of the same media (compressed / exported / edited variants and video
+ * cover frames) are named after the asset id, not after the primary file, so
+ * without it those copies are not found and survive the deletion.
+ */
+export type SecureDeleteOptions = {
+  /** The asset's id — how derived variants of it are named on disk. */
+  assetId?: string;
+  /** Base file name, used as a secondary match key for derived copies. */
+  fileName?: string;
+  /** A video's cover-frame URI: a real JPEG of the media, erased alongside it. */
+  coverUri?: string;
+  /**
+   * Additional copies to erase with the same guarantees — typically the asset's
+   * `cachePath` when its published document is the primary URI. Both are complete
+   * copies of the media, so erasing only one leaves the other recoverable.
+   */
+  extraUris?: string[];
+};
+
+/**
+ * Outcome of a native secure deletion.
+ *
+ * `deleted` and `securelyOverwritten` are deliberately separate: a file can be
+ * gone while the overwrite that was supposed to destroy its bytes failed, and
+ * the two must never be presented to the user the same way.
+ */
+export type SecureDeleteResult = {
+  /** The primary file is no longer on the filesystem. */
+  deleted: boolean;
+  /** Its bytes were overwritten AND flushed to storage before it was unlinked. */
+  securelyOverwritten: boolean;
+  /**
+   * Everything found was overwritten and nothing was left behind — the only
+   * flag that justifies reporting a secure deletion to the user.
+   */
+  fullySecure: boolean;
+  /** Exact size of the file before the overwrite, in bytes. */
+  originalBytes: number;
+  /** Bytes of garbage written over it, including the 2 MB past its end. */
+  overwrittenBytes: number;
+  /** Cached copies / derived variants also securely erased. */
+  derivedFilesErased: number;
+  /** Copies that could NOT be erased; non-zero means media may remain. */
+  derivedFilesFailed: number;
+  /** Present whenever any part of the operation fell short. */
+  error?: string;
+};
+
+/**
+ * Media move/copy result
+ */
+export type MediaPublishResult = {
+  success: boolean;
+  mediaId: string;
+  sourceLocation: MediaStorageLocation;
+  targetLocation: MediaStorageLocation;
+  sourceUri: string;
+  targetUri?: string;
+  fileHash?: string;
+  movedAt: number;
+  error?: {
+    code: string;
+    message: string;
+  };
+};
+
+/**
+ * Cleanup operation result
+ */
+export type CleanupResult = {
+  success: boolean;
+  filesRemoved: number;
+  spaceFreedMB: number;
+  erroredFiles: Array<{
+    path: string;
+    error: string;
+  }>;
+  timestamp: number;
+};
+
+/**
+ * Storage statistics
+ */
+export type StorageStats = {
+  cacheUsedMB: number;
+  documentUsedMB: number;
+  totalAvailableMB: number;
+  cachedItemsCount: number;
+  publishedItemsCount: number;
+  duplicateItemsCount: number;
+  oldestCacheItemAge: number;
+  newestCacheItemAge: number;
+};