@ethora/chat-component-rn 26.9.0 → 26.10.0

package/src/components/styled/SendInput.tsx

@@ -31,6 +31,18 @@ import {
   requestRecordingPermissionsAsync,
   RecordingPresets,
 } from 'expo-audio';
+import {
+  WAVEFORM_RESOLUTION,
+  encodeWaveForm,
+  meteringToLevel,
+  resamplePeaks,
+  scaleLevels,
+} from '../../helpers/audioWaveform';
+
+// The voice preset with metering on: the recorder's level, sampled while
+// recording, becomes the waveform the message carries (Telegram-style), so
+// receivers draw it without downloading and decoding the clip first.
+const VOICE_PRESET = { ...RecordingPresets.HIGH_QUALITY, isMeteringEnabled: true };
 
 // iOS photos default to HEIC; many web backends (incl. ours) 500 on
 // HEIC uploads because they can't decode it. Convert to JPEG before
@@ -121,12 +133,15 @@ const SendInput: React.FC<SendInputProps> = ({
   // Nothing claims the mic, writes a file, or switches the iOS session to
   // playAndRecord until `prepareToRecordAsync`, so consumers with
   // `enableAudio` off carry an idle object and nothing more.
-  const audioRecorder = useAudioRecorder(RecordingPresets.HIGH_QUALITY);
+  const audioRecorder = useAudioRecorder(VOICE_PRESET);
   // Tracks whether a recording is actually in flight, so cancel/stop and
   // the unmount teardown can tell "never started" from "needs stopping"
   // without reading native state.
   const isRecordingRef = useRef(false);
   const recordingTimerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  // Level samples of the take in flight, and when it started.
+  const recordingLevelsRef = useRef<number[]>([]);
+  const recordingStartedAtRef = useRef(0);
 
   // Refs shadow `message` and `filePreviews` so handleSendClick can:
   //   (a) read the LATEST typed value even when React state hasn't
@@ -425,16 +440,26 @@ const SendInput: React.FC<SendInputProps> = ({
       // side allocate a FRESH output file for this take. Without it the
       // recorder reuses the previous URL, so a second voice message would
       // overwrite the first while its upload is still in flight.
-      await audioRecorder.prepareToRecordAsync(RecordingPresets.HIGH_QUALITY);
+      await audioRecorder.prepareToRecordAsync(VOICE_PRESET);
       audioRecorder.record();
       isRecordingRef.current = true;
       setIsRecording(true);
       setRecordingDuration(0);
       const startedAt = Date.now();
-      // 250ms tick is fine for a seconds counter — keeps re-renders cheap.
+      recordingStartedAtRef.current = startedAt;
+      recordingLevelsRef.current = [];
+      // 100ms: often enough for the waveform's level samples; the seconds
+      // counter only re-renders when its value actually changes.
       recordingTimerRef.current = setInterval(() => {
+        try {
+          recordingLevelsRef.current.push(
+            meteringToLevel(audioRecorder.getStatus().metering)
+          );
+        } catch {
+          /* no level this tick */
+        }
         setRecordingDuration(Math.floor((Date.now() - startedAt) / 1000));
-      }, 250);
+      }, 100);
     } catch (err) {
       console.warn('startRecording failed', err);
       isRecordingRef.current = false;
@@ -495,10 +520,23 @@ const SendInput: React.FC<SendInputProps> = ({
     // matches the receiver's audio branch in MediaMessage (and
     // isLikelyAudio for any backend that strips mimetype).
     const ts = Date.now();
+    const levels = recordingLevelsRef.current;
+    recordingLevelsRef.current = [];
     const file: MediaFile = {
       uri,
       type: 'audio/m4a',
       name: `voice-${ts}.m4a`,
+      duration: Math.max(
+        1,
+        Math.round((ts - recordingStartedAtRef.current) / 1000)
+      ),
+      // No levels (metering unsupported) → no waveForm; receivers then
+      // decode the clip for its bars.
+      waveForm: levels.some((level) => level > 0)
+        ? encodeWaveForm(
+            scaleLevels(resamplePeaks(levels, WAVEFORM_RESOLUTION))
+          )
+        : undefined,
     };
     try {
       await sendMedia(file, file.type);

package/src/context/MessageNotificationContext.tsx

@@ -24,7 +24,7 @@ import {
   View,
 } from 'react-native';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
-import { useDispatch, useSelector } from 'react-redux';
+import { useDispatch, useSelector, useStore } from 'react-redux';
 import { messageNotificationManager } from '../utils/messageNotificationManager';
 import { setCurrentRoom } from '../roomStore/roomsSlice';
 import { IConfig, IMessage } from '../types/types';
@@ -33,6 +33,7 @@ import { useTheme } from '../hooks/useTheme';
 import { ProfileImagePlaceholder } from '../components/MainComponents/ProfileImagePlaceholder';
 import { useFileToken } from '../hooks/useFileToken';
 import { appendFileToken } from '../helpers/secureFileUrl';
+import { bareJid, shouldToastForRoom } from '../helpers/notificationPolicy';
 
 interface ToastItem {
   id: string;
@@ -102,6 +103,7 @@ export const MessageNotificationProvider: React.FC<ProviderProps> = ({
   // below is only its safety net.
   const pruneAfter = bannerMode ? duration + 2000 : duration;
 
+  const store = useStore<RootState>();
   const [toasts, setToasts] = useState<ToastItem[]>([]);
   const appActiveRef = useRef(AppState.currentState === 'active');
 
@@ -134,7 +136,8 @@ export const MessageNotificationProvider: React.FC<ProviderProps> = ({
   // Clear toasts when their room becomes active.
   useEffect(() => {
     if (!visibleRoomJID) {return;}
-    setToasts((prev) => prev.filter((t) => t.roomJID !== visibleRoomJID));
+    const open = bareJid(visibleRoomJID);
+    setToasts((prev) => prev.filter((t) => bareJid(t.roomJID) !== open));
   }, [visibleRoomJID]);
 
   const dismiss = useCallback((id: string) => {
@@ -170,8 +173,19 @@ export const MessageNotificationProvider: React.FC<ProviderProps> = ({
       roomJID: string
     ) => {
       if (!isEnabled) {return;}
-      // Don't toast for the currently active room.
-      if (visibleRoomJID && visibleRoomJID === roomJID) {return;}
+      // Decided on the store as it is NOW, not on this render's closure:
+      // the open chat, a muted chat and a backgrounded app never toast.
+      const rooms = store.getState().rooms;
+      if (
+        !shouldToastForRoom({
+          roomJID,
+          visibleRoomJID: rooms.visibleRoomJID,
+          appActive: appActiveRef.current,
+          muted: rooms.rooms[roomJID]?.muted,
+        })
+      ) {
+        return;
+      }
       const id = `msg-notification-${message.id}-${Date.now()}`;
       const item: ToastItem = {
         id,
@@ -188,7 +202,7 @@ export const MessageNotificationProvider: React.FC<ProviderProps> = ({
           : next;
       });
     },
-    [isEnabled, visibleRoomJID, maxNotifications]
+    [isEnabled, store, maxNotifications]
   );
 
   // Register with the global manager.

package/src/context/xmppProvider.tsx

@@ -14,6 +14,7 @@ import { VideoCallOverlay } from '../components/VideoCalls/VideoCallOverlay';
 import XmppClient, {
   XmppCredentialsProvider,
 } from '../networking/xmppClient';
+import { recoverXmppCredentials } from '../networking/xmppCredentials';
 import { refreshAuthTokensQuietly } from '../networking/authRefresh';
 import {
   IConfig,
@@ -31,12 +32,11 @@ import {
 } from '../utils/clientRegistry';
 import {
   applyResolvedUserToStore,
-  refreshUserCredentialsForXmpp,
   resolveInitBeforeLoadUser,
 } from '../helpers/resolveInitBeforeLoadUser';
 import { ensureScopedChatCache } from '../helpers/ensureScopedChatCache';
 import { getRooms as prefetchRoomsViaRest } from '../networking/api-requests/rooms.api';
-import { allRoomPresences } from '../networking/xmpp/allRoomPresences.xmpp';
+import { startBackgroundJoinSweep } from '../helpers/backgroundJoinSweep';
 import { pushSubscriptionService } from '../services/pushSubscriptionService';
 import { store } from '../roomStore';
 import {
@@ -58,7 +58,7 @@ import {
   getFlushBoundaryTs,
   getReadMarkerTimestamp,
 } from '../helpers/getServerReadTimestamp';
-import { runHistoryPreloadScheduler } from '../helpers/historyPreloadScheduler';
+import { runConfiguredHistoryPreload } from '../helpers/runConfiguredHistoryPreload';
 import { updateMessagesTillLast } from '../helpers/updateMessagesTillLast';
 import { secureUserStorage } from '../helpers/secureUserStorage';
 import { clearPersistedState } from '../roomStore/persistence';
@@ -103,10 +103,16 @@ const subscribeAllRoomsForPush = (client: any, reason: string) => {
     .catch((e) => devPushLog('warn', `${reason}: mucsub subscribe failed`, e));
 };
 
+/** Emitted once the session ended because the XMPP password is gone for good. */
+export const SESSION_LOST_EVENT = 'ethora:sessionLost';
+
 export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, isVisible }) => {
   const [client, setClient] = useState<XmppClient | null>(null);
   const [providerBootstrapStatus, setProviderBootstrapStatus] =
     useState<ProviderBootstrapStatus>('idle');
+  // Bumped by "Retry": the bootstrap effect keys on it, so a retry re-runs
+  // the bootstrap with the same config instead of waiting for a change.
+  const [bootstrapNonce, setBootstrapNonce] = useState(0);
 
   // Track which "init mode" this provider runs in. When config.initBeforeLoad
   // is true, the provider owns bootstrap and ChatWrapper just waits.
@@ -126,62 +132,7 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
   // Returns last-known cached creds if nothing usable is available so
   // the XmppClient at least doesn't crash on `undefined.password`.
   const credentialsProvider = useMemo<XmppCredentialsProvider>(() => {
-    return async () => {
-      // 1. Make sure the REST tokens are fresh before re-minting XMPP
-      //    creds. This used to call `config.refreshTokens.refreshFunction`
-      //    directly and then fall into step 2, which refreshes again —
-      //    two rotations back to back, which the new backend scheme
-      //    reads as a race at best and token reuse at worst. One call to
-      //    the shared rotation point covers both the consumer-supplied
-      //    function and the built-in endpoint.
-      if (config?.refreshTokens?.enabled) {
-        const rotated = await refreshAuthTokensQuietly({ force: true });
-
-        if (rotated?.xmppPassword) {
-          const rotatedUser = store.getState().chatSettingStore.user;
-          return {
-            username:
-              rotatedUser?.xmppUsername ||
-              rotatedUser?.defaultWallet?.walletAddress ||
-              '',
-            password: rotated.xmppPassword,
-          };
-        }
-      }
-
-      // 2. Re-mint XMPP creds via the right priority chain for the
-      //    current auth mode. This call ALWAYS hydrates (unlike
-      //    `resolveInitBeforeLoadUser` which short-circuits when a
-      //    cached user already has xmppCredentials).
-      const fresh = await refreshUserCredentialsForXmpp(config).catch(
-        (err) => {
-          devPushLog('warn', 'XMPP creds refresh: full chain failed', err);
-          return null;
-        }
-      );
-      if (fresh) {
-        applyResolvedUserToStore(fresh);
-        return {
-          username:
-            fresh.xmppUsername ||
-            fresh.defaultWallet?.walletAddress ||
-            '',
-          password: fresh.xmppPassword || '',
-        };
-      }
-
-      // 3. Last-resort: return the cached creds so reconnect() can
-      //    still attempt a connection. If the original failure was
-      //    a stale JWT this will fail again and the user has to
-      //    re-mount the chat — but at least we don't break the
-      //    transient-network-blip case where the cached creds are
-      //    still valid.
-      const u = store.getState().chatSettingStore.user;
-      return {
-        username: u?.xmppUsername || u?.defaultWallet?.walletAddress || '',
-        password: u?.xmppPassword || '',
-      };
-    };
+    return () => recoverXmppCredentials(config);
   }, [
     config?.jwtLogin?.enabled,
     config?.jwtLogin?.token,
@@ -248,6 +199,10 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
           .performLogout()
           .catch(() => {})
           .finally(() => {
+            // The chat says so on its own screen (ChatWrapper's overlay)
+            // for a host that keeps it mounted; the host is told too, so
+            // it can route to its sign-in.
+            DeviceEventEmitter.emit(SESSION_LOST_EVENT);
             try {
               Promise.resolve(config?.logout?.onAfterLogout?.()).catch(() => {});
             } catch {
@@ -258,23 +213,30 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
 
       // Re-join MUC rooms on every 'online'. After a reconnect the new
       // XMPP stream isn't a member of any room, so a sent message gets a
-      // local double-tick but never reaches the room (bug #21). Re-sending
-      // presence on reconnect fixes delivery. On the very first connect
-      // the room list isn't loaded yet so this joins nothing — the
-      // bootstrap's own allRoomPresences handles that pass.
+      // local double-tick but never reaches the room (bug #21). The join is
+      // a background sweep (open room first, then recent activity, a few at
+      // a time) shared with the client's own online handler, so it neither
+      // blocks anything nor doubles up. A send / history fetch / room open
+      // also joins its own room on demand. On the very first connect the
+      // room list isn't loaded yet so this joins little - the bootstrap
+      // starts its own sweep once /chats/my has landed.
       created.setOnOnline(() => {
         const underlying = (created as any).client;
         if (!underlying) {return;}
-        // The headers say "Updating…" until the rooms are joined again and
+        // The headers say "Updating..." until the rooms are joined again and
         // the archive caught up - a stream that is up is not yet a chat
         // that is. Same tick as the client's own 'online', so the title
         // never shows the plain state in between.
         store.dispatch(setConnectionState('syncing'));
-        const rejoin = allRoomPresences(underlying)
+        // The join sweep is shared with the client's own online handler
+        // (it dedupes); here it is only awaited so the state can settle.
+        const rejoin = Promise.resolve()
+          .then(() => created.sendAllPresencesAndMarkReady?.())
           .catch((e) =>
-            devPushLog('warn', 'reconnect: allRoomPresences re-join failed', e)
-          )
-          .finally(() => subscribeAllRoomsForPush(underlying, 'reconnect'));
+            devPushLog('warn', 'reconnect: background join sweep failed', e)
+          );
+        // Push (mucsub) does not depend on the join: subscribe right away.
+        subscribeAllRoomsForPush(underlying, 'reconnect');
         // Also refresh the private store so unread / lastViewed markers
         // are accurate after a long reconnect — the MUC re-join above only
         // restores delivery, not unread state. Idempotent on first connect.
@@ -448,7 +410,7 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
           }
         }
 
-        // Kick off REST /chats/my; allRoomPresences below needs the
+        // Kick off REST /chats/my; the background join sweep below needs the
         // room list to be in redux, otherwise it joins 0 MUCs and the
         // user receives zero realtime messages until they manually tap
         // into each room. Track the promise so we can await it before
@@ -485,14 +447,15 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
         try {
           await restRoomsPromise;
         } catch {}
-        try {
-          const roomCount = Object.keys(store.getState().rooms.rooms || {}).length;
-          devPushLog('xmpp', `initBeforeLoad: joining ${roomCount} rooms via presence…`);
-          await allRoomPresences((c as any).client);
-          devPushLog('xmpp', 'initBeforeLoad: allRoomPresences ok');
-        } catch (e) {
-          devPushLog('warn', 'initBeforeLoad: allRoomPresences failed', e);
-        }
+        // The room list is complete (REST /chats/my seeded it): join the
+        // rooms in the BACKGROUND. READY below does not wait for it: a
+        // sweep over hundreds of rooms would otherwise hold the whole room
+        // list behind it. Open room first, then recent activity; sends,
+        // history fetches and opening a room join their own room on demand.
+        const roomCount = Object.keys(store.getState().rooms.rooms || {}).length;
+        devPushLog('xmpp', `initBeforeLoad: joining ${roomCount} rooms in the background`);
+        startBackgroundJoinSweep(c);
+        // Push (mucsub) needs the room list, not the joins.
         subscribeAllRoomsForPush((c as any).client, 'initBeforeLoad');
 
         store.dispatch(setStoreClient(c));
@@ -503,21 +466,14 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
         setProviderBootstrapStatus('ready');
         devPushLog('rn', 'initBeforeLoad: READY');
 
-        // Background-prefetch history for every room (fire-and-forget).
-        const qos = config?.historyQoS;
-        const activeRoomJID = store.getState().rooms.activeRoomJID || null;
-        const defaultRoomJids =
-          (config?.defaultRooms as any[])?.map((r) =>
-            typeof r === 'string' ? r : r?.jid
-          ).filter(Boolean) || [];
-        runHistoryPreloadScheduler({
+        // Background history preload (fire-and-forget; does not wait for
+        // the join sweep: MAM needs no join, and each fetch joins its own
+        // room best-effort). Staged by default: the top rooms by activity
+        // first, everything else loads when opened. See `historyPreload`.
+        runConfiguredHistoryPreload({
           client: c,
           signal: abortController.signal,
-          selectedRoomJid: activeRoomJID,
-          defaultRoomJids,
-          concurrency: qos?.stagedPreloadConcurrency,
-          pageSize: qos?.stagedPreloadFirstPassSize,
-          roomLimit: qos?.preloadTopKRooms,
+          config,
         }).catch((err) => console.warn('History preload scheduler failed', err));
       } catch (error: any) {
         if (cancelled || abortController.signal.aborted) {return;}
@@ -584,6 +540,7 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
     config?.jwtLogin?.enabled,
     config?.jwtLogin?.token,
     config?.xmppSettings?.devServer,
+    bootstrapNonce,
   ]);
 
   // -----------------------------------------------------------
@@ -701,7 +658,14 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
       // only USED here for the one-shot stamp+flush, matching customer
       // #42: leaving (or backgrounding) a room while scrolled up must not
       // mark messages the user never reached as read.
-      visibleBeforeBackground = visibleRoomJID;
+      // iOS leaves in two steps, 'inactive' then 'background', and the
+      // first one already cleared visibility below. Overwriting here on the
+      // second would forget the open chat, so it was never re-marked
+      // visible on return: the chat on screen then counted unread and
+      // raised in-app toasts for its own messages. Remember, never forget.
+      if (visibleRoomJID) {
+        visibleBeforeBackground = visibleRoomJID;
+      }
       let boundaryTs: number | null = null;
       if (visibleRoomJID) {
         boundaryTs = state.rooms?.readBoundaries?.[visibleRoomJID] ?? null;
@@ -933,6 +897,7 @@ export const XmppProvider: React.FC<XmppProviderProps> = ({ children, config, is
       completedBootstrapKeyRef.current = '';
       inflightBootstrapKeyRef.current = '';
       setProviderBootstrapStatus('idle');
+      setBootstrapNonce((n) => n + 1);
     });
     return () => sub.remove();
   }, []);

package/src/helpers/audioWaveform.ts

@@ -0,0 +1,142 @@
+/**
+ * Waveform helpers for voice messages: the bars a bubble draws, the
+ * `waveForm` string a sender attaches to the message, and the recorder's
+ * metering turned into the same bars.
+ */
+
+/** Floor for a bar, as a fraction of the box: silence is still a dot. */
+export const MIN_BAR = 0.08;
+
+/** Resolution a waveform is computed and sent at; bubbles resample it. */
+export const WAVEFORM_RESOLUTION = 64;
+
+/**
+ * Bars for one clip, from its PCM samples — the same curve as the web
+ * client's `buildWaveformPeaks`, so a voice note looks the same on both.
+ *
+ * RMS per bucket (what the ear hears, not the worst sample), scaled against
+ * the 95th percentile so a single click cannot set the scale, then a
+ * square-root curve because loudness is perceived that way, and a floor so
+ * a quiet passage still reads as a bar rather than as nothing.
+ *
+ * The decoder WebView carries a copy of this in plain JS (it cannot import
+ * modules); keep the two in step.
+ */
+export const buildWaveformPeaks = (
+  samples: ArrayLike<number>,
+  barCount: number
+): number[] => {
+  const bars = Math.max(1, Math.floor(barCount));
+  const bucket = Math.floor(samples.length / bars);
+  if (bucket < 1) {return new Array(bars).fill(MIN_BAR);}
+
+  const rms: number[] = [];
+  for (let i = 0; i < bars; i += 1) {
+    let sum = 0;
+    for (let j = i * bucket; j < (i + 1) * bucket; j += 1) {
+      sum += samples[j]! * samples[j]!;
+    }
+    rms.push(Math.sqrt(sum / bucket));
+  }
+  return scaleLevels(rms);
+};
+
+/**
+ * Raw per-bar levels (RMS, or linear amplitude from the recorder) → 0..1
+ * bars, against the 95th percentile with the square-root curve and floor.
+ */
+export const scaleLevels = (levels: number[]): number[] => {
+  if (!levels.length) {return [];}
+  const sorted = [...levels].sort((a, b) => a - b);
+  const reference =
+    sorted[Math.floor(sorted.length * 0.95)] || sorted[sorted.length - 1] || 0;
+  if (reference <= 0) {return levels.map(() => MIN_BAR);}
+  return levels.map((value) => {
+    const scaled = Math.sqrt(Math.min(value / reference, 1));
+    return Math.min(1, MIN_BAR + scaled * (1 - MIN_BAR));
+  });
+};
+
+/**
+ * Stretch or squeeze bars to `count`, taking the loudest bar in each slot
+ * when squeezing so a short loud word is not averaged away.
+ */
+export const resamplePeaks = (peaks: number[], count: number): number[] => {
+  const target = Math.max(1, Math.floor(count));
+  if (!peaks.length) {return new Array(target).fill(MIN_BAR);}
+  if (peaks.length === target) {return peaks;}
+  const out: number[] = [];
+  for (let i = 0; i < target; i += 1) {
+    const from = Math.floor((i * peaks.length) / target);
+    const to = Math.max(from + 1, Math.floor(((i + 1) * peaks.length) / target));
+    let max = 0;
+    for (let j = from; j < to && j < peaks.length; j += 1) {
+      max = Math.max(max, peaks[j]!);
+    }
+    out.push(max);
+  }
+  return out;
+};
+
+/**
+ * Recorder metering (dBFS, about -160..0) → linear amplitude 0..1, which
+ * `scaleLevels` then treats like an RMS. Anything at or below -60 dB is
+ * room noise and counts as silence.
+ */
+export const meteringToLevel = (db: number | undefined): number => {
+  if (typeof db !== 'number' || !Number.isFinite(db) || db <= -60) {return 0;}
+  return Math.pow(10, Math.min(db, 0) / 20);
+};
+
+/**
+ * The `waveForm` attribute a voice message carries: comma-separated bar
+ * heights, 0..100. Short enough for a stanza attribute, plain enough for
+ * any client to read.
+ */
+export const encodeWaveForm = (peaks: number[]): string =>
+  peaks
+    .map((p) => Math.round(Math.max(0, Math.min(1, p)) * 100))
+    .join(',');
+
+/**
+ * Bars from a message's `waveForm`, or null when it has none / nothing
+ * usable. Accepts the comma list above and a JSON array, in 0..1 or 0..100.
+ */
+export const parseWaveForm = (value: unknown): number[] | null => {
+  if (typeof value !== 'string' || !value.trim()) {return null;}
+  let raw: unknown[];
+  const text = value.trim();
+  if (text.startsWith('[')) {
+    try {
+      const parsed = JSON.parse(text);
+      if (!Array.isArray(parsed)) {return null;}
+      raw = parsed;
+    } catch {
+      return null;
+    }
+  } else {
+    raw = text.split(',');
+  }
+  const numbers = raw.map((n) => Number(n));
+  if (numbers.length < 2 || numbers.some((n) => !Number.isFinite(n) || n < 0)) {
+    return null;
+  }
+  const max = Math.max(...numbers);
+  const scale = max > 1 ? 100 : 1;
+  return numbers.map((n) => Math.max(MIN_BAR, Math.min(1, n / scale)));
+};
+
+/** Seconds from a message's `duration` attribute, or 0 when absent. */
+export const parseDurationSeconds = (value: unknown): number => {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? n : 0;
+};
+
+/** `0:07`, `1:23`, `12:05`. */
+export const formatClipTime = (millis: number): string => {
+  const safe = Number.isFinite(millis) && millis > 0 ? millis : 0;
+  const totalSec = Math.floor(safe / 1000);
+  const min = Math.floor(totalSec / 60);
+  const sec = totalSec % 60;
+  return `${min}:${sec.toString().padStart(2, '0')}`;
+};

package/src/helpers/backgroundJoinSweep.ts

@@ -0,0 +1,35 @@
+/**
+ * Starting the MUC join sweep without ever waiting for it.
+ *
+ * The room list is usable as soon as /chats/my has returned (rooms are
+ * seeded with lastMessage / unread / usersCnt), so joining every room is a
+ * background job: open room first, then recent activity, a few at a time.
+ */
+
+type SweepClient = { sendAllPresencesAndMarkReady?: () => Promise<unknown> };
+
+// Fire-and-forget: never awaited by the room list, never throws.
+export const startBackgroundJoinSweep = (client: SweepClient | null | undefined) => {
+  if (!client || typeof client.sendAllPresencesAndMarkReady !== 'function') {
+    return;
+  }
+  Promise.resolve()
+    .then(() => client.sendAllPresencesAndMarkReady?.())
+    .catch((error) => {
+      console.warn('[loadRooms] background join sweep failed', error);
+    });
+};
+
+// Ends the loading state right after the rooms fetch and joins in the
+// background. Resolves without waiting for any join; a failing fetch starts
+// no sweep and never calls `onListReady`.
+export const loadRoomsThenJoinInBackground = async <T,>(
+  client: SweepClient,
+  fetchRooms: () => Promise<T>,
+  onListReady: () => void
+): Promise<T> => {
+  const rooms = await fetchRooms();
+  startBackgroundJoinSweep(client);
+  onListReady();
+  return rooms;
+};

package/src/helpers/bubbleHighlight.ts

@@ -0,0 +1,47 @@
+import { useSyncExternalStore } from 'react';
+
+/** How long the jump highlight stays on a bubble. */
+export const HIGHLIGHT_MS = 1000;
+
+interface Highlight {
+  id: string;
+  /** Epoch ms the highlight ends. */
+  until: number;
+}
+
+let current: Highlight | null = null;
+const listeners = new Set<() => void>();
+const emit = () => listeners.forEach((listener) => listener());
+
+/**
+ * Highlight the bubble of one message for HIGHLIGHT_MS (a jump just landed on
+ * it), or clear the highlight with null. Kept outside the list on purpose: a
+ * row that is unmounted and mounted again while the highlight is running (the
+ * list recycles rows as the scroll settles) reads the same state, so the
+ * highlight follows the message instead of being lost with the row.
+ */
+export const setBubbleHighlight = (id: string | null, now = Date.now()): void => {
+  current = id === null ? null : { id, until: now + HIGHLIGHT_MS };
+  emit();
+};
+
+export const getBubbleHighlightUntil = (id: string): number =>
+  current && current.id === id ? current.until : 0;
+
+const subscribe = (listener: () => void) => {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+};
+
+/**
+ * End time (epoch ms) of the highlight of this message, 0 when it has none.
+ * The snapshot is a number, so only the highlighted row re-renders.
+ */
+export const useBubbleHighlightUntil = (id: string): number =>
+  useSyncExternalStore(
+    subscribe,
+    () => getBubbleHighlightUntil(id),
+    () => 0
+  );