@ethora/chat-component-rn 26.5.21 → 26.6.10

package/src/roomStore/chatSettingsSlice.ts

@@ -10,6 +10,7 @@ import {
   User,
 } from '../types/types';
 import { Iso639_1Codes } from '../types/models/language.model';
+import type { TranslateMode } from '../utils/translateModePolicy';
 import { localStorageConstants } from '../helpers/constants/LOCAL_STORAGE';
 import { asyncLocalStorage } from '../hooks/useLocalStorage';
 
@@ -22,6 +23,13 @@ export interface ChatState {
   activeFile?: ModalFile;
   client?: any;
   langSource?: Iso639_1Codes;
+  /**
+   * The reader's own auto/manual pick from the language modal's switcher.
+   * Undefined until they touch it, at which point it wins over the host's
+   * `config.translates.mode` default (unless the host pinned `forceType`).
+   * See utils/translateModePolicy.
+   */
+  translateMode?: TranslateMode;
 }
 
 export const unpackAndTransform = (input?: User): User => {
@@ -152,6 +160,7 @@ const reducers = {
     state.config = undefined;
     state.client = undefined;
     state.langSource = undefined;
+    state.translateMode = undefined;
     asyncLocalStorage(localStorageConstants.ETHORA_USER).remove();
   },
   setLangSource: (
@@ -160,6 +169,12 @@ const reducers = {
   ) => {
     state.langSource = action.payload;
   },
+  setTranslateMode: (
+    state: WritableDraft<ChatState>,
+    action: PayloadAction<TranslateMode | undefined>
+  ) => {
+    state.translateMode = action.payload;
+  },
 };
 
 export const chatSlice: Slice<ChatState, typeof reducers, 'chat'> = createSlice({
@@ -180,6 +195,7 @@ export const {
   setActiveFile,
   setStoreClient,
   setLangSource,
+  setTranslateMode,
 } = chatSlice.actions;
 
 export default chatSlice.reducer;

package/src/roomStore/index.ts

@@ -2,6 +2,7 @@ import { configureStore, combineReducers } from '@reduxjs/toolkit';
 import chatSettingsReducer, { setUser } from './chatSettingsSlice';
 import roomsSlice, { addRoom } from './roomsSlice';
 import { roomHeapSlice } from './roomHeapSlice';
+import callReducer from './callSlice';
 import { IRoom } from '../types/types';
 import { unreadMiddleware } from './Middleware/unreadMidlleware';
 import { logoutMiddleware } from './Middleware/logoutMiddleware';
@@ -13,6 +14,10 @@ const rootReducer = combineReducers({
   chatSettingStore: chatSettingsReducer,
   rooms: roomsSlice,
   roomHeapSlice: roomHeapSlice.reducer,
+  // Live call state. Deliberately NOT persisted: a call that was ringing
+  // when the app was killed is over by the time it reopens, and restoring
+  // it would put the user straight into a dead LiveKit room.
+  call: callReducer,
 });
 
 export type RootState = ReturnType<typeof rootReducer>;

package/src/roomStore/persistence.ts

@@ -49,10 +49,99 @@ const sanitizeUser = (user?: User): User | null => {
   } as User;
 };
 
+// What a persisted message is FOR: instantly painting a recent transcript
+// on reload before MAM catches up. That needs the fields the bubbles and
+// room-list previews actually read, nothing else. Everything outside this
+// list is either re-derived on render or re-fetched from the server.
+const PERSISTED_MESSAGE_FIELDS: (keyof IMessage)[] = [
+  'id',
+  'xmppId',
+  'xmppFrom',
+  'body',
+  'date',
+  'timestamp',
+  'roomJid',
+  'isSystemMessage',
+  'isMediafile',
+  'isDeleted',
+  'isEdited',
+  'isReply',
+  'showInChannel',
+  'mainMessage',
+  'mimetype',
+  'location',
+  'locationPreview',
+  'fileName',
+  'originalName',
+  'size',
+  'langSource',
+  'callLog',
+];
+
+// The sender identity that rides along on every message over the wire
+// (senderFirstName / senderLastName / photo, which createMessageFromXml
+// folds into message.user) is NOT what the UI reads back, and is not ours
+// to cache: `usersSet` is the canonical store for names and avatars, and
+// the renderers resolve through it, re-deriving the name every time
+// usersSet updates. That is what keeps a renamed user from staying stale.
+//
+// Persisting a copy per message duplicated the same handful of identities
+// across every message of every room, and optimistic sends spread the
+// ENTIRE logged-in user into message.user (see useSendMessage), auth
+// material included.
+//
+// Keep `id` (the key usersSet is looked up by) and `name`, nothing else.
+// `name` earns its ~15 chars: broadcast/system senders ("Ethora") never
+// enter usersSet at all, so for those the message is the only place the
+// name exists.
+const PERSISTED_MESSAGE_USER_FIELDS = ['id', 'name'] as const;
+
+// Room fields that are pure server state, re-fetched on every load, and so
+// must never sit in the message cache, let alone compete with messages for
+// AsyncStorage space.
+//
+// `members` is the one that matters. A 3.5k-member room serializes to
+// roughly 840k chars, several hundred times the rest of the room object
+// put together. A handful of such rooms is megabytes of roster written on
+// every debounce tick, and on Android AsyncStorage that means blown
+// cursor-window limits and multi-second writes, for data createRoomFromApi
+// repopulates from /chats/my on the very next load. `usersCnt`, which the
+// header actually reads, is its own scalar field and is preserved below.
+const REFETCHED_ROOM_FIELDS = ['members'] as const;
+
+const pickDefined = <T extends object>(
+  source: T,
+  keys: readonly (keyof T)[]
+): Partial<T> => {
+  const out: Partial<T> = {};
+  for (const key of keys) {
+    const value = source?.[key];
+    if (value !== undefined) {
+      out[key] = value;
+    }
+  }
+  return out;
+};
+
+const compactMessageForPersist = (message: IMessage): IMessage => {
+  const compact = pickDefined(message, PERSISTED_MESSAGE_FIELDS) as IMessage;
+  const user = message?.user as Record<string, any> | undefined;
+  if (user) {
+    compact.user = pickDefined(
+      user,
+      PERSISTED_MESSAGE_USER_FIELDS as unknown as readonly string[]
+    ) as IMessage['user'];
+  }
+  return compact;
+};
+
 const sanitizeMessages = (messages: IMessage[]): IMessage[] => {
   if (!Array.isArray(messages)) {return [];}
-  if (messages.length <= MESSAGE_LIMIT) {return messages;}
-  return messages.slice(-MESSAGE_LIMIT);
+  const capped =
+    messages.length > MESSAGE_LIMIT
+      ? messages.slice(-MESSAGE_LIMIT)
+      : messages;
+  return capped.map(compactMessageForPersist);
 };
 
 const sanitizeRooms = (
@@ -63,8 +152,19 @@ const sanitizeRooms = (
   for (const [jid, room] of Object.entries(rooms)) {
     if (!jid || typeof jid !== 'string' || !jid.includes('@')) {continue;}
     if (!room || typeof room !== 'object' || Array.isArray(room)) {continue;}
+
+    const compactRoom = { ...room } as Record<string, any>;
+    // Preserve the count the header reads before dropping the roster it
+    // would otherwise be derived from.
+    if (compactRoom.usersCnt === undefined && Array.isArray(room.members)) {
+      compactRoom.usersCnt = room.members.length;
+    }
+    for (const field of REFETCHED_ROOM_FIELDS) {
+      delete compactRoom[field];
+    }
+
     out[jid] = {
-      ...room,
+      ...(compactRoom as IRoom),
       messages: sanitizeMessages(room?.messages || []),
       composing: false,
       composingList: [],

package/src/roomStore/roomsSlice.ts

@@ -15,6 +15,97 @@ import type XmppClient from '../networking/xmppClient';
 // just fetched. After cap eviction we drop from the head (oldest).
 const RUNTIME_MESSAGE_LIMIT = 100;
 
+// Body strings the server uses for call signaling broadcasts (call-token,
+// call-state ringing/ended, etc). These should never reach the chat
+// transcript or the room-list "last message" preview, they're control
+// frames, not user-visible content. The XMPP handler (onCallTokenMessage)
+// already swallows them in the live stream, but they can still arrive via
+// MAM history, mucsub catchup, or be present in persisted state from
+// before that filter existed. Drop them at the reducer boundary so the
+// transcript stays clean regardless of source.
+const CALL_SIGNAL_BODIES = new Set([
+  'call-token',
+  'call-state',
+  'call-ringing',
+  'call-ended',
+  'call-declined',
+  'call-cancelled',
+  'call-canceled',
+  'call-timeout',
+  'call-rejected',
+  'call-invite',
+]);
+
+const isCallSignalMessage = (message: IMessage | undefined | null): boolean => {
+  if (!message) {return false;}
+  const body = String(message.body || '').trim().toLowerCase();
+  return CALL_SIGNAL_BODIES.has(body);
+};
+
+const stripCallSignals = (messages: IMessage[] | undefined): IMessage[] =>
+  Array.isArray(messages)
+    ? messages.filter((message) => !isCallSignalMessage(message))
+    : [];
+
+// True for the client-side call-log fallback written at hangup: it exists
+// only in this client's store (id "calllog-<callId>"), never on the server.
+const isLocalCallLogEntry = (message: IMessage | undefined | null): boolean =>
+  String(message?.id || '').startsWith('calllog-');
+
+// Merge two log entries for the SAME callId into one. Identity (id/date/
+// xmppId) comes from the server copy when one side is the local fallback,
+// the server archive id is what MAM pages and the catch-up anchor will
+// match against later. Display (body/callLog) comes from whichever copy
+// saw the larger duration, so partial per-participant call-states don't
+// shrink it.
+const mergeCallLogEntries = (a: IMessage, b: IMessage): IMessage => {
+  const aLocal = isLocalCallLogEntry(a);
+  const bLocal = isLocalCallLogEntry(b);
+  const identity = aLocal === bLocal ? a : aLocal ? b : a;
+  const display =
+    (a.callLog?.durationMs || 0) >= (b.callLog?.durationMs || 0) ? a : b;
+  if (identity === display) {return identity;}
+  return {
+    ...display,
+    id: identity.id,
+    xmppId: identity.xmppId ?? display.xmppId,
+    date: identity.date ?? display.date,
+  };
+};
+
+// Collapse call-log duplicates for the same callId inside a merged history
+// list (the live path dedups in addRoomMessage, but a MAM page merged over
+// a persisted local fallback entry would otherwise show the call twice).
+const collapseCallLogDuplicates = (messages: IMessage[]): IMessage[] => {
+  const byCallId = new Map<string, IMessage>();
+  let hasDuplicates = false;
+  for (const message of messages) {
+    const callId = message?.callLog?.callId;
+    if (!callId) {continue;}
+    const existing = byCallId.get(callId);
+    if (existing) {
+      hasDuplicates = true;
+      byCallId.set(callId, mergeCallLogEntries(existing, message));
+    } else {
+      byCallId.set(callId, message);
+    }
+  }
+  if (!hasDuplicates) {return messages;}
+  const emitted = new Set<string>();
+  return messages
+    .filter((message) => {
+      const callId = message?.callLog?.callId;
+      if (!callId) {return true;}
+      if (emitted.has(callId)) {return false;}
+      emitted.add(callId);
+      return true;
+    })
+    .map((message) => {
+      const callId = message?.callLog?.callId;
+      return callId ? byCallId.get(callId) || message : message;
+    });
+};
+
 const enforceMessageCap = (messages: IMessage[]): void => {
   // Trim oldest until we're at/under the limit. Mutates in place
   // (immer-compatible inside reducers).
@@ -45,8 +136,11 @@ function mergeHistoryIntoCache(
   existing: IMessage[] | undefined,
   fetched: IMessage[] | undefined
 ): IMessage[] {
-  const ex = Array.isArray(existing) ? existing : [];
-  const fe = Array.isArray(fetched) ? fetched : [];
+  // Strip call control frames on BOTH sides before merging: they can be
+  // in the cache (persisted from before this filter existed) and in the
+  // fetched MAM page (the live-stream swallow doesn't cover history).
+  const ex = stripCallSignals(existing);
+  const fe = stripCallSignals(fetched);
 
   const pending = ex.filter((m) => m?.pending);
   const realExisting = ex.filter(
@@ -69,7 +163,10 @@ function mergeHistoryIntoCache(
 
   // Cold room, or a gap (no shared id) → can't merge → use the fresh page.
   if (realExisting.length === 0 || !overlaps) {
-    return [...capTail(realFetched.slice().sort(byMs)), ...pending];
+    return [
+      ...capTail(collapseCallLogDuplicates(realFetched.slice().sort(byMs))),
+      ...pending,
+    ];
   }
 
   // Overlap → union + dedupe by id. Fetched wins on collision: it carries
@@ -87,7 +184,9 @@ function mergeHistoryIntoCache(
       prev?.isEdited && !m.isEdited ? { ...m, isEdited: true } : m
     );
   }
-  const merged = Array.from(byId.values()).sort(byMs);
+  const merged = collapseCallLogDuplicates(
+    Array.from(byId.values()).sort(byMs)
+  );
   return [...capTail(merged), ...pending];
 }
 
@@ -335,6 +434,14 @@ const reducers = {
     ) {
       const { roomJID, message, start } = action.payload;
 
+      // Call signaling broadcasts ("call-token", "call-state", etc.)
+      // sometimes slip past the live XMPP filter (MAM history, mucsub
+      // catch-up), drop them here so they never land in the transcript
+      // or the room-list "last message" preview.
+      if (isCallSignalMessage(message)) {
+        return;
+      }
+
       // Guard against the "stanza arrived before /chats/my completed"
       // race — without this, the optional-chain `?.messages` falls
       // back to undefined, and the assignment below tries to set
@@ -350,6 +457,33 @@ const reducers = {
       }
 
       const roomMessages = state.rooms[roomJID].messages;
+
+      // Collapse multiple call-state events for the same call into a single
+      // log entry. Sources: the client-side fallback written at hangup (id
+      // "calllog-<callId>", exists only locally) and the server broadcast(s),
+      // which can fire once per participant leaving (earlier ones carry a
+      // partial durationMs). Rules:
+      //  - the SERVER copy is canonical for identity (id/date/xmppId): its
+      //    archive id is what MAM and the catch-up anchor return later, so
+      //    keeping a local "calllog-" id around breaks anchor matching and
+      //    duplicates the entry on the next history merge;
+      //  - the LARGEST duration wins for display, so a 2-minute call doesn't
+      //    render as "2 sec".
+      const incomingCallLog = message.callLog;
+      if (incomingCallLog?.callId) {
+        const existingCallIdx = roomMessages.findIndex(
+          (msg) => msg.callLog?.callId === incomingCallLog.callId
+        );
+        if (existingCallIdx !== -1) {
+          const existing = roomMessages[existingCallIdx];
+          const merged = mergeCallLogEntries(existing as IMessage, message);
+          if (merged !== (existing as IMessage)) {
+            roomMessages[existingCallIdx] = merged;
+          }
+          return;
+        }
+      }
+
       const lengthBefore = roomMessages.length;
 
       if (roomMessages.length === 0 || start) {
@@ -666,6 +800,16 @@ const reducers = {
         }
       }
     },
+    // Merges resolved room members into the identity cache Message.tsx /
+    // resolveSenderDisplayName read from. Keyed by BOTH the bare local
+    // part and the full jid so either lookup style hits — a message's
+    // `user.id` can be either depending on how it was parsed.
+    mergeUsersSet(
+      state: WritableDraft<RoomMessagesState>,
+      action: PayloadAction<{ members: Record<string, any> }>
+    ) {
+      state.usersSet = { ...(state.usersSet || {}), ...action.payload.members };
+    },
 };
 
 export const roomsStore: Slice<RoomMessagesState, typeof reducers, 'roomMessages'> = createSlice({
@@ -770,6 +914,7 @@ export const {
   setPendingNotificationJid,
   clearPendingNotificationJid,
   setReactions,
+  mergeUsersSet,
 } = roomsStore.actions;
 
 export default roomsStore.reducer;

package/src/types/models/language.model.ts

@@ -1,4 +1,20 @@
-export type Iso639_1Codes = 'en' | 'es' | 'pt' | 'ht' | 'zh';
+// Regional variants for the three languages LANGUAGE_OPTIONS currently
+// offers, matching the deployment's actual reader regions: Canadian
+// English/French, US Spanish. Bare 2-letter codes stay valid alongside
+// them (toBaseLanguage reduces either form to the same base for i18n
+// string-table lookups and translation-language comparisons), since other
+// flows (config.translates.translations) still produce or accept the bare
+// form.
+export type Iso639_1Codes =
+  | 'en'
+  | 'en-CA'
+  | 'es'
+  | 'es-US'
+  | 'pt'
+  | 'ht'
+  | 'fr'
+  | 'fr-CA'
+  | 'zh';
 
 export interface Language {
   iso639_1: Iso639_1Codes;

package/src/types/models/message.model.ts

@@ -36,6 +36,15 @@ export interface IMessage {
   // Set once a message has been corrected via XEP-0308 (<replace>), so the
   // bubble can show a small "edited" marker (Slack/WhatsApp style).
   isEdited?: boolean;
+  // Present when this message is a call-log entry derived from a
+  // `<data type="call-state">` stanza (see helpers/callLogMessage.ts).
+  callLog?: {
+    callId: string;
+    direction: 'outgoing' | 'incoming';
+    durationMs: number;
+    missed: boolean;
+    kind: 'audio' | 'video';
+  };
 }
 
 export interface ReactionMessage {

package/src/types/types.ts

@@ -401,7 +401,7 @@ export interface IConfig {
    * When `true`, an idle input (no text, no attachments) shows a
    * microphone in the send-button slot; tap → start recording → stop &
    * send. iOS apps need `NSMicrophoneUsageDescription` in Info.plist
-   * (add via `expo-av`'s plugin block in `app.json`). Receiving voice
+   * (add via `expo-audio`'s plugin block in `app.json`). Receiving voice
    * messages from other clients (incl. legacy web `.bin` voicemails) is
    * independent of this flag — incoming audio plays regardless.
    */
@@ -594,13 +594,96 @@ export interface IConfig {
   customSystemMessage?: React.ComponentType<MessageProps>;
 
   // ----- translations -----
-  translates?: { enabled: boolean; translations?: Iso639_1Codes };
+  translates?: {
+    enabled: boolean;
+    translations?: Iso639_1Codes;
+    /**
+     * 'auto' shows the translation inline automatically. 'manual' shows a
+     * "Translate" link the reader taps (LinkedIn-style), then renders the
+     * result inline with a "Show original" toggle. Default 'auto'.
+     *
+     * Neither mode calls any translation service, both only ever display
+     * `message.translations`, whatever arrived attached to the stanza (see
+     * `readerLocale` below for how a message gets translated in the first
+     * place). This is purely a display choice: show it immediately, or let
+     * the reader ask for it.
+     */
+    mode?: 'auto' | 'manual';
+    /**
+     * Pins `mode` as fixed host policy. When true, the language-selector
+     * modal's auto/manual switcher does not render at all, and the reader
+     * has no way to override `mode`, it's always whatever the host set.
+     * Defaults to false: the reader can flip between auto and manual
+     * themselves via the switcher, which then wins over `mode` (the host's
+     * declared default, used until the reader touches it).
+     */
+    forceType?: boolean;
+    /**
+     * Reader's full locale (BCP-47, e.g. "fr-CA"). Falls back to
+     * `config.i18n.locale`. The region is passed through to `onTranslate` so
+     * the service can distinguish fr-CA vs fr-FR; the Translate button
+     * visibility comparison ignores the region (en-US vs en-CA => no button).
+     *
+     * This is also how a host drives the reader's language from OUTSIDE the
+     * chat component: set it (e.g. from your own app's language switcher)
+     * and pass the updated config down as a normal prop.
+     */
+    readerLocale?: string;
+    /**
+     * Shows/hides the globe-icon language picker in the chat header.
+     * Defaults to true whenever `enabled` is true. Set to false when the
+     * host manages the reader's language itself (via `readerLocale`) and
+     * an in-chat picker would just be a second, redundant control.
+     */
+    showLanguageSelector?: boolean;
+    /**
+     * Shows/hides the list of selectable languages INSIDE the picker
+     * (English/Espanol/...). Defaults to true. Set to false to keep only
+     * the enable/disable-translates toggle.
+     */
+    showLanguageList?: boolean;
+    /**
+     * Host-provided translation function. When set, the manual Translate
+     * action calls this, wire it to your own service, instead of reading
+     * `message.translations`. Optional; omit to use only what already
+     * arrived over XMPP.
+     */
+    onTranslate?: (
+      text: string,
+      ctx: { sourceLocale?: string; targetLocale: string; message: IMessage }
+    ) => Promise<string>;
+    /**
+     * Host predicate deciding whether to show the Translate action for a
+     * given message. When omitted, the component compares base languages
+     * (message source vs reader, region ignored) and shows the action when
+     * they differ.
+     */
+    showTranslateForMessage?: (message: IMessage) => boolean;
+  };
+  /**
+   * Static UI i18n (interface captions like "Search...", "Type message").
+   * `locale` is a BCP-47 tag the host passes from the device/user (e.g. "en",
+   * "fr-CA", "es-US"); captions resolve to its base language. `strings`
+   * overrides or extends any built-in caption by key (see src/i18n/strings.ts).
+   * Built-in languages: en, fr, es, pt, ht, zh. Independent from `translates`
+   * (dynamic per-message translation).
+   */
+  i18n?: {
+    locale?: string;
+    strings?: Record<string, string>;
+  };
   enableTranslates?: boolean;
 
   // ----- notifications -----
   inAppNotifications?: InAppNotificationConfig;
   pushNotifications?: {
     enabled?: boolean;
+    /**
+     * Base URL of the push subscription service, including the version
+     * segment (e.g. "https://push.chat.ethora.com/api/v1"). Set this for
+     * self-hosted or enterprise deployments; omit to use Ethora's.
+     */
+    apiUrl?: string;
     iconPath?: string;
     badgePath?: string;
     onClick?: (params: {
@@ -640,6 +723,63 @@ export interface IConfig {
       messageType: 'text' | 'media';
     }) => void;
   };
+
+  // ----- audio / video calls -----
+  /**
+   * LiveKit-backed 1:1 audio and video calls. Off unless `enabled` is
+   * explicitly `true`. Requires the native peer dependencies
+   * `@livekit/react-native` and `@livekit/react-native-webrtc`, plus
+   * microphone/camera permissions and the background audio modes listed
+   * in the README. Expo Go cannot run these, the host app needs a dev
+   * build or a prebuilt binary.
+   */
+  videoCalls?: VideoCallsConfig;
+}
+
+/**
+ * Override the icons used by the in-call control bar and the incoming-call
+ * ring screen. Each value is any React node. When omitted, the chat's
+ * built-in icon is used. The mic/camera/screen-share toggles take separate
+ * on/off icons so the host can express active vs muted however they like.
+ */
+export interface VideoCallIcons {
+  micOn?: React.ReactNode;
+  micOff?: React.ReactNode;
+  cameraOn?: React.ReactNode;
+  cameraOff?: React.ReactNode;
+  screenShareOn?: React.ReactNode;
+  screenShareOff?: React.ReactNode;
+  hangup?: React.ReactNode;
+  accept?: React.ReactNode;
+  decline?: React.ReactNode;
+}
+
+export interface VideoCallsConfig {
+  enabled: boolean;
+  livekitUrl: string;
+  allowedRoomTypes?: Array<'private'>;
+  /**
+   * Show the audio-only call button next to the video-call button. Off by
+   * default: it's a separate opt-in feature. An audio call uses the same
+   * call backend as video (no server changes needed); the client just
+   * starts the session with `kind: 'audio'` so no camera track is
+   * published, and the callee learns the kind from the direct
+   * `call-invite` signal. Requires `enabled` and a `livekitUrl` like
+   * video calls.
+   */
+  enableAudioCalls?: boolean;
+  /** Start a video call with the camera already on. Default true. */
+  startWithCameraOn?: boolean;
+  /** Start a call with the microphone already on. Default true. */
+  startWithMicOn?: boolean;
+  /**
+   * Show the screen-share control. Default false on React Native: screen
+   * capture needs a foreground service on Android and a Broadcast Upload
+   * Extension on iOS, neither of which the SDK can add to a host app.
+   */
+  showScreenShare?: boolean;
+  /** Custom icons for the call control bar / ring screen. */
+  icons?: VideoCallIcons;
 }
 
 interface ConfigRoom {

package/src/utils/translateModePolicy.ts

@@ -0,0 +1,31 @@
+import { IConfig } from '../types/types';
+
+export type TranslateMode = 'auto' | 'manual';
+
+/**
+ * Whether the reader is allowed to pick auto vs manual themselves via the
+ * language-selector modal's switcher. `forceType: true` means the host has
+ * pinned `translates.mode` as policy, the switcher must not even render,
+ * let alone let a reader flip it.
+ */
+export const canReaderChooseTranslateMode = (
+  translates?: IConfig['translates']
+): boolean => !translates?.forceType;
+
+/**
+ * The mode actually in effect for this reader right now.
+ *
+ * `forceType` wins unconditionally, even a leftover `readerMode` from
+ * before the host turned forcing on must not leak through. Otherwise the
+ * reader's own pick (if they've touched the switcher) wins over the host's
+ * declared default, and the host's `mode` (defaulting to 'auto') is the
+ * fallback for a reader who never has.
+ */
+export const resolveTranslateMode = (
+  translates?: IConfig['translates'],
+  readerMode?: TranslateMode
+): TranslateMode => {
+  const hostDefault: TranslateMode = translates?.mode || 'auto';
+  if (translates?.forceType) {return hostDefault;}
+  return readerMode || hostDefault;
+};