@micha.bigler/ui-core-micha 2.15.0 → 2.16.0

package/src/messaging/PollCard.jsx

@@ -0,0 +1,36 @@
+import { Alert, Button, Checkbox, FormControlLabel, Paper, Stack, Typography } from '@mui/material';
+import { useEffect, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { extractApiErrorMessage, useMessaging } from './MessagingProvider';
+
+/** Independently mountable live poll view. Server authorization remains authoritative. */
+export function PollCard({ message, canClose: canCloseProp }) {
+  const { t } = useTranslation();
+  const { castPollVote, closeConversationPoll, currentUser } = useMessaging();
+  const poll = message?.poll;
+  const [selected, setSelected] = useState([]);
+  const [error, setError] = useState(null);
+  const [busy, setBusy] = useState(false);
+  useEffect(() => setSelected((poll?.options || []).filter((option) => option.selected || option.voted).map((option) => option.id)), [poll]);
+  if (!poll) return null;
+  const closed = Boolean(poll.closed_at);
+  const creatorId = poll.created_by?.id ?? poll.created_by;
+  const canClose = canCloseProp ?? poll.can_close ?? message?.can_close ?? message?.permissions?.can_close ?? (creatorId != null && creatorId === currentUser?.id);
+  const changeSelection = (id) => setSelected((current) => poll.allow_multiple ? (current.includes(id) ? current.filter((value) => value !== id) : [...current, id]) : (current.includes(id) ? [] : [id]));
+  const vote = async () => {
+    if (!selected.length) { setError(t('MessagingPoll.SELECT_OPTION')); return; }
+    setBusy(true); setError(null);
+    try { await castPollVote(message.id, poll, selected); } catch (voteError) { setError(t('MessagingPoll.VOTE_ERROR', { message: extractApiErrorMessage(voteError) })); } finally { setBusy(false); }
+  };
+  const close = async () => {
+    setBusy(true); setError(null);
+    try { await closeConversationPoll(message.id, poll); } catch (closeError) { setError(t('MessagingPoll.CLOSE_ERROR', { message: extractApiErrorMessage(closeError) })); } finally { setBusy(false); }
+  };
+  return <Paper variant="outlined" sx={{ p: 1 }} aria-label={t('MessagingPoll.LABEL')}><Stack spacing={0.5}>
+    <Typography variant="subtitle2">{poll.question}</Typography>
+    {(poll.options || []).map((option) => <FormControlLabel key={option.id} disabled={closed || busy} control={<Checkbox checked={selected.includes(option.id)} onChange={() => changeSelection(option.id)} />} label={`${option.text || option.label} (${option.vote_count ?? option.votes_count ?? 0})`} />)}
+    {error && <Alert severity="error" role="alert">{error}</Alert>}
+    <Stack direction="row" spacing={1}><Button size="small" onClick={vote} disabled={closed || busy}>{t('MessagingPoll.VOTE')}</Button>{canClose && !closed && <Button size="small" color="warning" onClick={close} disabled={busy}>{t('MessagingPoll.CLOSE')}</Button>}{closed && <Typography variant="caption">{t('MessagingPoll.CLOSED')}</Typography>}</Stack>
+  </Stack></Paper>;
+}

package/src/messaging/ReactionBar.jsx

@@ -0,0 +1,46 @@
+import AddReactionOutlinedIcon from '@mui/icons-material/AddReactionOutlined';
+import { Alert, Chip, IconButton, Stack } from '@mui/material';
+import { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { extractApiErrorMessage, useMessaging } from './MessagingProvider';
+
+const QUICK_EMOJIS = ['👍', '❤️', '😂', '🎉', '👀'];
+
+/** Independently mountable aggregate reaction controls for one message. */
+export function ReactionBar({ message }) {
+  const { t } = useTranslation();
+  const { toggleReaction } = useMessaging();
+  const [expanded, setExpanded] = useState(false);
+  const [error, setError] = useState(null);
+  // Tracks in-flight emoji toggles for this message so a rapid double-click
+  // can't fire two concurrent requests for the same emoji — toggleReaction's
+  // rollback-on-failure reverts to a pre-optimistic snapshot, which would
+  // silently discard a second, already-succeeded change if both were in
+  // flight at once. Disabling the chip while its own request is pending
+  // removes the race instead of trying to make concurrent toggles safe.
+  const [pending, setPending] = useState(() => new Set());
+  const reactions = message?.reactions || [];
+  const react = async (emoji, active = false) => {
+    if (pending.has(emoji)) return;
+    setError(null);
+    setPending((current) => new Set(current).add(emoji));
+    try { await toggleReaction(message.id, emoji, active); }
+    catch (reactionError) { setError(t('MessagingReactions.ERROR', { message: extractApiErrorMessage(reactionError) })); }
+    finally { setPending((current) => { const next = new Set(current); next.delete(emoji); return next; }); }
+  };
+  return <Stack spacing={0.5} aria-label={t('MessagingReactions.LABEL')}>
+    <Stack direction="row" spacing={0.5} flexWrap="wrap">
+      {reactions.map((reaction) => <Chip key={reaction.emoji} size="small" disabled={pending.has(reaction.emoji)} color={reaction.reacted ? 'primary' : 'default'} label={`${reaction.emoji} ${reaction.count || 0}`} onClick={() => react(reaction.emoji, Boolean(reaction.reacted))} aria-label={t('MessagingReactions.TOGGLE', { emoji: reaction.emoji, count: reaction.count || 0 })} />)}
+      <IconButton size="small" aria-label={t('MessagingReactions.ADD')} onClick={() => setExpanded((value) => !value)}><AddReactionOutlinedIcon fontSize="small" /></IconButton>
+    </Stack>
+    {expanded && <Stack direction="row" spacing={0.25} flexWrap="wrap">{QUICK_EMOJIS.map((emoji) => {
+      // A quick-emoji already reflected in the aggregate row must toggle it
+      // off, not re-add it — otherwise clicking an already-reacted emoji here
+      // optimistically double-increments the count before the API call.
+      const existing = reactions.find((reaction) => reaction.emoji === emoji);
+      return <Chip key={emoji} size="small" disabled={pending.has(emoji)} color={existing?.reacted ? 'primary' : 'default'} label={emoji} onClick={() => { react(emoji, Boolean(existing?.reacted)); setExpanded(false); }} />;
+    })}</Stack>}
+    {error && <Alert severity="error" role="alert">{error}</Alert>}
+  </Stack>;
+}

package/src/messaging/ReadTicks.jsx

@@ -0,0 +1,23 @@
+import { Tooltip, Typography } from '@mui/material';
+import { useEffect, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { useMessaging } from './MessagingProvider';
+
+/** Renders only the aggregate receipt unless the server explicitly supplies permitted detail. */
+export function ReadTicks({ messageId, conversation }) {
+  const { t } = useTranslation();
+  const { getMessageReadStatus } = useMessaging();
+  const [status, setStatus] = useState(null);
+  useEffect(() => {
+    let mounted = true;
+    getMessageReadStatus(messageId).then((next) => { if (mounted) setStatus(next); }).catch(() => { if (mounted) setStatus(null); });
+    return () => { mounted = false; };
+  }, [getMessageReadStatus, messageId]);
+  if (!status) return null;
+  const label = status.all_read ? t('MessagingReadTicks.ALL_READ') : t('MessagingReadTicks.DELIVERED', { count: status.delivered_count || 0 });
+  // The server never returns DM detail; enforce the same carve-out defensively.
+  const detail = conversation?.kind === 'direct' ? null : status.recipient_detail;
+  const detailText = detail?.map((recipient) => recipient.display_name || recipient.username || recipient.user_id).filter(Boolean).join(', ');
+  return <Tooltip title={detailText || label}><Typography component="span" variant="caption" color="text.secondary" aria-label={label}>{label}</Typography></Tooltip>;
+}

package/src/messaging/Thread.jsx

@@ -0,0 +1,71 @@
+import { Alert, Box, Button, CircularProgress, Divider, Stack, Typography } from '@mui/material';
+import { useCallback, useContext, useMemo, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { AuthContext } from '../auth/AuthContext';
+import { MessageBubble } from './MessageBubble';
+import { useMessaging } from './MessagingProvider';
+import { ReadTicks } from './ReadTicks';
+
+function chronological(messages) { return [...messages].sort((left, right) => new Date(left.created_at || 0) - new Date(right.created_at || 0)); }
+// A still-pending optimistic row (chunk 4) has a fake `local-<requestId>` id
+// and no durable server row yet — mounting ReadTicks against it would fire a
+// getMessageReadStatus REST call for an id the server has never heard of.
+// Wait for reconciliation (status !== 'pending') before showing read state.
+function canShowReadTicks(message, user) {
+  return Boolean(user?.id) && message.sender?.id === user.id && message.status !== 'pending';
+}
+
+/**
+ * A standalone timeline. Compose/reaction/poll/attachment mutations remain
+ * separate chunk collaborators.
+ *
+ * ReadTicks is only mounted for the current user's own messages (matches
+ * jg's `shouldShowReadTick(msg, isOwn)`): a read receipt tells the sender
+ * whether their own message was seen, not the recipient anything about a
+ * message they're currently reading. Gating here also bounds the number of
+ * `getMessageReadStatus` REST calls a rendered timeline fires — one per own
+ * message shown, not one per message in the conversation.
+ */
+export function Thread({ conversationId, onReplyTargetChange }) {
+  const { t } = useTranslation();
+  const { user } = useContext(AuthContext) || {};
+  const { cache, loadMoreMessages, loadThreadReplies } = useMessaging();
+  const scrollRef = useRef(null);
+  const [loadingOlder, setLoadingOlder] = useState(false);
+  const [error, setError] = useState(null);
+  const [replyingTo, setReplyingTo] = useState(null);
+  const [openThreads, setOpenThreads] = useState({});
+  const conversation = cache.conversations[conversationId];
+  const roots = useMemo(() => chronological(Object.values(cache.messages).filter((message) => message.conversation_id === conversationId && !message.reply_to)), [cache.messages, conversationId]);
+
+  const loadOlder = useCallback(async () => {
+    setLoadingOlder(true); setError(null);
+    try { await loadMoreMessages(conversationId); } catch { setError(t('MessagingThread.LOAD_ERROR')); } finally { setLoadingOlder(false); }
+  }, [conversationId, loadMoreMessages, t]);
+  const onScroll = () => { if (scrollRef.current?.scrollTop === 0 && cache.cursors.messages[conversationId] && !loadingOlder) loadOlder(); };
+  const reply = (message) => { setReplyingTo(message); onReplyTargetChange?.(message); };
+  const toggleReplies = async (root) => {
+    if (!openThreads[root.id]) {
+      try { await loadThreadReplies(root.id); } catch { setError(t('MessagingThread.REPLIES_ERROR')); return; }
+    }
+    setOpenThreads((current) => ({ ...current, [root.id]: !current[root.id] }));
+  };
+  return (
+    <Stack spacing={1} sx={{ minWidth: 0 }}>
+      {error && <Alert severity="error" role="alert">{error}</Alert>}
+      {replyingTo && <Alert severity="info" onClose={() => { setReplyingTo(null); onReplyTargetChange?.(null); }}>{t('MessagingThread.REPLYING_TO', { sender: replyingTo.sender?.display_name || t('MessagingThread.UNKNOWN_SENDER') })}</Alert>}
+      <Box ref={scrollRef} onScroll={onScroll} sx={{ maxHeight: 560, overflowY: 'auto', px: 0.5 }} aria-label={t('MessagingThread.TIMELINE')}>
+        {cache.cursors.messages[conversationId] && <Box textAlign="center" py={1}><Button onClick={loadOlder} disabled={loadingOlder}>{loadingOlder ? <CircularProgress size={18} /> : t('MessagingThread.LOAD_OLDER')}</Button></Box>}
+        {!roots.length && <Typography color="text.secondary" textAlign="center" py={4}>{t('MessagingThread.EMPTY')}</Typography>}
+        <Stack spacing={1}>{roots.map((message) => {
+          const replies = chronological(Object.values(cache.messages).filter((item) => item.reply_to === message.id));
+          return <Stack key={message.id} spacing={0.75}><MessageBubble message={message} onReply={reply}>{canShowReadTicks(message, user) && <ReadTicks messageId={message.id} conversation={conversation} />}</MessageBubble>
+            {(message.reply_count || replies.length) > 0 && <Button size="small" onClick={() => toggleReplies(message)}>{openThreads[message.id] ? t('MessagingThread.HIDE_REPLIES') : t('MessagingThread.SHOW_REPLIES', { count: message.reply_count || replies.length })}</Button>}
+            {openThreads[message.id] && <Stack spacing={0.75} sx={{ pl: 3, borderLeft: 2, borderColor: 'divider' }}>{replies.map((item) => <MessageBubble key={item.id} message={item} replyTo={message} onReply={reply}>{canShowReadTicks(item, user) && <ReadTicks messageId={item.id} conversation={conversation} />}</MessageBubble>)}</Stack>}
+            <Divider /></Stack>;
+        })}</Stack>
+      </Box>
+    </Stack>
+  );
+}

package/src/messaging/api.js

@@ -0,0 +1,47 @@
+import apiClient from '../auth/apiClient';
+
+const BASE_URL = '/api/messaging/';
+const conversationsUrl = `${BASE_URL}conversations/`;
+
+function data(response) {
+  return response.data;
+}
+
+function requestConfig({ cursor, params, headers } = {}) {
+  return {
+    ...(params ? { params } : {}),
+    ...(cursor ? { params: { ...(params || {}), cursor } } : {}),
+    ...(headers ? { headers } : {}),
+  };
+}
+
+export function listConversations({ cursor, ...filters } = {}) {
+  return apiClient.get(conversationsUrl, requestConfig({ cursor, params: filters })).then(data);
+}
+export function createDirectConversation(payload) { return apiClient.post(`${conversationsUrl}direct/`, payload).then(data); }
+export function createGroupConversation(payload) { return apiClient.post(`${conversationsUrl}group/`, payload).then(data); }
+export function createBroadcastConversation(payload) { return apiClient.post(`${conversationsUrl}broadcast/`, payload).then(data); }
+export function createManagedConversation(payload) { return apiClient.post(`${conversationsUrl}managed/`, payload).then(data); }
+export function createObjectThreadConversation(payload) { return apiClient.post(`${conversationsUrl}object-thread/`, payload).then(data); }
+export function getConversationConfig(conversationId) { return apiClient.get(`${conversationsUrl}${conversationId}/config/`).then(data); }
+export function patchConversationConfig(conversationId, patch) { return apiClient.patch(`${conversationsUrl}${conversationId}/config/`, patch).then(data); }
+export function archiveConversation(conversationId, archived) { return apiClient.post(`${conversationsUrl}${conversationId}/archive/`, { archived }).then(data); }
+export function patchConversationPreferences(conversationId, patch) { return apiClient.post(`${conversationsUrl}${conversationId}/preferences/`, patch).then(data); }
+export function listMessages(conversationId, { cursor } = {}) { return apiClient.get(`${conversationsUrl}${conversationId}/messages/`, requestConfig({ cursor })).then(data); }
+export function createMessage(conversationId, payload, { idempotencyKey } = {}) { return apiClient.post(`${conversationsUrl}${conversationId}/messages/`, payload, requestConfig({ headers: idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : undefined })).then(data); }
+export function uploadAttachments(conversationId, formData, { idempotencyKey } = {}) { return apiClient.post(`${conversationsUrl}${conversationId}/attachments/`, formData, requestConfig({ headers: idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : undefined })).then(data); }
+export function createPoll(conversationId, payload, { idempotencyKey } = {}) { return apiClient.post(`${conversationsUrl}${conversationId}/polls/`, payload, requestConfig({ headers: idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : undefined })).then(data); }
+export function getMessage(messageId) { return apiClient.get(`${BASE_URL}messages/${messageId}/`).then(data); }
+export function patchMessage(messageId, patch) { return apiClient.patch(`${BASE_URL}messages/${messageId}/`, patch).then(data); }
+export function deleteMessage(messageId) { return apiClient.delete(`${BASE_URL}messages/${messageId}/`).then(data); }
+export function addReaction(messageId, emoji) { return apiClient.post(`${BASE_URL}messages/${messageId}/reactions/`, { emoji }).then(data); }
+export function removeReaction(messageId, emoji) { return apiClient.delete(`${BASE_URL}messages/${messageId}/reactions/${encodeURIComponent(emoji)}/`).then(data); }
+export function listThread(rootId, { cursor } = {}) { return apiClient.get(`${BASE_URL}messages/${rootId}/thread/`, requestConfig({ cursor })).then(data); }
+export function markThreadRead(rootId, readAt) { return apiClient.post(`${BASE_URL}messages/${rootId}/thread/read/`, readAt ? { read_at: readAt } : {}).then(data); }
+export function markConversationRead(conversationId, readAt) { return apiClient.post(`${conversationsUrl}${conversationId}/read/`, readAt ? { read_at: readAt } : {}).then(data); }
+export function getReadStatus(messageId) { return apiClient.get(`${BASE_URL}messages/${messageId}/read-status/`).then(data); }
+export function votePoll(pollId, optionIds) { return apiClient.post(`${BASE_URL}polls/${pollId}/vote/`, { option_ids: optionIds }).then(data); }
+export function closePoll(pollId) { return apiClient.post(`${BASE_URL}polls/${pollId}/close/`).then(data); }
+export function getAttachment(attachmentId) { return apiClient.get(`${BASE_URL}attachments/${attachmentId}/`, { responseType: 'blob' }).then(data); }
+export function getAttachmentThumbnail(attachmentId) { return apiClient.get(`${BASE_URL}attachments/${attachmentId}/thumbnail/`, { responseType: 'blob' }).then(data); }
+export function getUnreadCount() { return apiClient.get(`${BASE_URL}unread-count/`).then(data); }

package/src/notifications/NotificationsProvider.jsx

@@ -89,7 +89,7 @@ export function NotificationsProvider({ children, wsUrlBase }) {
   // arrived and patched state before the initial REST response landed.
   const [seeded, setSeeded] = useState(false);
 
-  const { subscribe } = useRealtimeCore({
+  const { subscribe, onReconnect } = useRealtimeCore({
     active: authenticated && seeded,
     wsUrl: getWebSocketUrl(wsUrlBase),
   });
@@ -200,7 +200,7 @@ export function NotificationsProvider({ children, wsUrlBase }) {
   const markDone = useCallback((ids) => mark('done', ids), [mark]);
 
   return (
-    <RealtimeContext.Provider value={{ subscribe }}>
+    <RealtimeContext.Provider value={{ subscribe, onReconnect }}>
       <NotificationsContext.Provider value={{
         notifications,
         unreadCount,

package/src/notifications/realtime.jsx

@@ -33,6 +33,7 @@ export { RealtimeContext };
 export function useRealtimeCore({ active, wsUrl }) {
   const socketRef = useRef(null);
   const subscribersRef = useRef(new Map());
+  const reconnectSubscribersRef = useRef(new Set());
 
   const subscribe = useCallback((envelope, handler) => {
     const subscribers = subscribersRef.current;
@@ -50,12 +51,21 @@ export function useRealtimeCore({ active, wsUrl }) {
     };
   }, []);
 
+  // Additive lifecycle signal for domains whose REST projections must be
+  // refreshed after the one shared transport reconnects. It deliberately does
+  // not alter the socket/backoff ownership or the envelope subscriber API.
+  const onReconnect = useCallback((handler) => {
+    reconnectSubscribersRef.current.add(handler);
+    return () => reconnectSubscribersRef.current.delete(handler);
+  }, []);
+
   useEffect(() => {
     if (!active) return undefined;
 
     let isActive = true;
     let reconnectTimer = null;
     let backoffMs = INITIAL_BACKOFF_MS;
+    let hasConnected = false;
 
     const handleMessage = (event) => {
       let data;
@@ -85,6 +95,16 @@ export function useRealtimeCore({ active, wsUrl }) {
 
       socket.onopen = () => {
         backoffMs = INITIAL_BACKOFF_MS;
+        if (hasConnected) {
+          reconnectSubscribersRef.current.forEach((handler) => {
+            try {
+              handler();
+            } catch (error) {
+              console.error('Realtime reconnect subscriber error', error);
+            }
+          });
+        }
+        hasConnected = true;
       };
       socket.onmessage = handleMessage;
       socket.onerror = () => {
@@ -114,5 +134,5 @@ export function useRealtimeCore({ active, wsUrl }) {
     };
   }, [active, wsUrl]);
 
-  return { subscribe };
+  return { subscribe, onReconnect };
 }

package/tests/ConversationList.test.jsx

@@ -0,0 +1,66 @@
+// @vitest-environment jsdom
+import React from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+
+vi.mock('react-i18next', () => ({ useTranslation: () => ({ t: (key) => key }) }));
+vi.mock('../src/notifications/realtime', () => ({ useRealtime: () => ({ subscribe: () => () => {}, onReconnect: () => () => {} }) }));
+
+import { ConversationList } from '../src/messaging/ConversationList';
+import { MessagingProvider } from '../src/messaging/MessagingProvider';
+
+function renderList(api, props = {}) {
+  return render(<MessagingProvider api={api}><ConversationList onOpen={props.onOpen} {...props} /></MessagingProvider>);
+}
+
+describe('ConversationList', () => {
+  let api;
+  beforeEach(() => {
+    api = {
+      listConversations: vi.fn().mockResolvedValue({ results: [{ id: 1, title: 'First', unread_count: 2, last_message: { body: 'Hello' } }], next_cursor: 'opaque-cursor' }),
+      getUnreadCount: vi.fn().mockResolvedValue({ unread_count: 2, by_conversation: { 1: 2 } }),
+      listMessages: vi.fn().mockResolvedValue({ results: [] }),
+      archiveConversation: vi.fn().mockResolvedValue({ id: 1, archived: true }),
+      patchConversationPreferences: vi.fn().mockResolvedValue({ id: 1, muted: true }),
+      createGroupConversation: vi.fn().mockResolvedValue({ id: 4, title: 'Volunteers', kind: 'group' }),
+      createBroadcastConversation: vi.fn().mockResolvedValue({ id: 5, title: 'Announcements', kind: 'broadcast' }),
+    };
+  });
+  afterEach(cleanup);
+
+  it('loads the next opaque cursor page without offset assumptions', async () => {
+    api.listConversations.mockResolvedValueOnce({ results: [{ id: 1, title: 'First' }], next_cursor: 'opaque-cursor' }).mockResolvedValueOnce({ results: [{ id: 2, title: 'Second' }], next_cursor: null });
+    renderList(api);
+    await screen.findByText('First');
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingList.LOAD_MORE' }));
+    await screen.findByText('Second');
+    // Append, not replace: the first page's item must still be present.
+    expect(screen.getByText('First')).toBeTruthy();
+    expect(api.listConversations).toHaveBeenLastCalledWith({ cursor: 'opaque-cursor' });
+  });
+
+  it('opens host-provided group and broadcast launchers into normalized list state', async () => {
+    const onOpen = vi.fn();
+    renderList(api, { onOpen, groupLaunchers: [{ id: 'volunteers', label: 'Volunteers', payload: { title: 'Volunteers' } }], broadcastLauncher: { label: 'Announcements', payload: {} } });
+    await screen.findByText('First');
+    fireEvent.click(screen.getByRole('button', { name: 'Volunteers' }));
+    await waitFor(() => expect(api.createGroupConversation).toHaveBeenCalledWith({ title: 'Volunteers' }));
+    expect(onOpen).toHaveBeenCalledWith(expect.objectContaining({ id: 4 }));
+    fireEvent.click(screen.getByRole('button', { name: 'Announcements' }));
+    await waitFor(() => expect(api.createBroadcastConversation).toHaveBeenCalled());
+    // Once opened it becomes a normal (unread/preview-bearing) list row; the
+    // static launcher button must not keep showing it a second time.
+    await waitFor(() => expect(screen.queryByRole('button', { name: 'Announcements' })).toBeNull());
+  });
+
+  it('wires mute and archive through participant APIs', async () => {
+    renderList(api);
+    await screen.findByText('First');
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingList.ACTIONS' }));
+    fireEvent.click(screen.getByText('MessagingList.MUTE'));
+    await waitFor(() => expect(api.patchConversationPreferences).toHaveBeenCalledWith(1, { muted: true }));
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingList.ACTIONS' }));
+    fireEvent.click(screen.getByText('MessagingList.ARCHIVE'));
+    await waitFor(() => expect(api.archiveConversation).toHaveBeenCalledWith(1, true));
+  });
+});

package/tests/MessagingProvider.test.jsx

@@ -0,0 +1,50 @@
+// @vitest-environment jsdom
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+import { act, render, screen, waitFor } from '@testing-library/react';
+
+import { RealtimeContext } from '../src/notifications/realtime';
+import { MessagingProvider, useMessaging } from '../src/messaging/MessagingProvider';
+
+function Harness() { const { cache } = useMessaging(); return <output data-testid="cache">{JSON.stringify(cache)}</output>; }
+function makeTransport() {
+  const handlers = new Set(); const reconnectHandlers = new Set();
+  return { subscribe: vi.fn((_envelope, handler) => { handlers.add(handler); return () => handlers.delete(handler); }), onReconnect: vi.fn((handler) => { reconnectHandlers.add(handler); return () => reconnectHandlers.delete(handler); }), frame: (frame) => handlers.forEach((handler) => handler(frame)), reconnect: () => reconnectHandlers.forEach((handler) => handler()) };
+}
+function renderProvider({ transport = makeTransport(), api, activeConversationId = 1, active } = {}) {
+  const props = { api, activeConversationId, ...(active === undefined ? {} : { active }) };
+  render(<RealtimeContext.Provider value={transport}><MessagingProvider {...props}><Harness /></MessagingProvider></RealtimeContext.Provider>);
+  return transport;
+}
+const cache = () => JSON.parse(screen.getByTestId('cache').textContent);
+
+describe('MessagingProvider', () => {
+  it('deduplicates repeated event IDs and only changes the affected message slice', async () => {
+    const api = { listConversations: vi.fn().mockResolvedValue({ results: [{ id: 1 }, { id: 2 }] }), listMessages: vi.fn().mockResolvedValue({ results: [{ id: 10, conversation_id: 2, body: 'unchanged' }] }), getUnreadCount: vi.fn().mockResolvedValue({ unread_count: 0, by_conversation: {} }) };
+    const transport = renderProvider({ api }); await waitFor(() => expect(api.listConversations).toHaveBeenCalled());
+    const frame = { envelope: 'messaging', type: 'message', event_id: 'once', conversation_id: 1, message: { id: 11, body: 'new' } };
+    act(() => { transport.frame(frame); transport.frame(frame); });
+    expect(Object.keys(cache().messages)).toEqual(['10', '11']);
+    expect(cache().messages['10'].body).toBe('unchanged');
+  });
+
+  it('refetches list, active thread and unread state when Layer 1 reconnects', async () => {
+    const api = { listConversations: vi.fn().mockResolvedValue({ results: [] }), listMessages: vi.fn().mockResolvedValue({ results: [] }), getUnreadCount: vi.fn().mockResolvedValue({ unread_count: 0, by_conversation: {} }) };
+    const transport = renderProvider({ api }); await waitFor(() => expect(api.listMessages).toHaveBeenCalledTimes(1));
+    await act(async () => transport.reconnect());
+    await waitFor(() => { expect(api.listConversations).toHaveBeenCalledTimes(2); expect(api.listMessages).toHaveBeenLastCalledWith(1); expect(api.getUnreadCount).toHaveBeenCalledTimes(2); });
+  });
+
+  it('does not call the authenticated-only REST surface while active=false, and starts fetching once it flips true', async () => {
+    const api = { listConversations: vi.fn().mockResolvedValue({ results: [] }), listMessages: vi.fn().mockResolvedValue({ results: [] }), getUnreadCount: vi.fn().mockResolvedValue({ unread_count: 0, by_conversation: {} }) };
+    const transport = makeTransport();
+    const { rerender } = render(<RealtimeContext.Provider value={transport}><MessagingProvider api={api} activeConversationId={1} active={false}><Harness /></MessagingProvider></RealtimeContext.Provider>);
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(api.listConversations).not.toHaveBeenCalled();
+    expect(api.listMessages).not.toHaveBeenCalled();
+    expect(api.getUnreadCount).not.toHaveBeenCalled();
+
+    rerender(<RealtimeContext.Provider value={transport}><MessagingProvider api={api} activeConversationId={1} active><Harness /></MessagingProvider></RealtimeContext.Provider>);
+    await waitFor(() => expect(api.listConversations).toHaveBeenCalledTimes(1));
+  });
+});

package/tests/Thread.test.jsx

@@ -0,0 +1,100 @@
+// @vitest-environment jsdom
+import React from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+
+vi.mock('react-i18next', () => ({ useTranslation: () => ({ t: (key, options) => options?.count != null ? `${key}:${options.count}` : key }) }));
+vi.mock('../src/notifications/realtime', () => ({ useRealtime: () => ({ subscribe: () => () => {}, onReconnect: () => () => {} }) }));
+
+import { AuthContext } from '../src/auth/AuthContext';
+import { MessageBubble } from '../src/messaging/MessageBubble';
+import { MessagingProvider } from '../src/messaging/MessagingProvider';
+import { ReadTicks } from '../src/messaging/ReadTicks';
+import { Thread } from '../src/messaging/Thread';
+
+function makeApi() {
+  return {
+    listConversations: vi.fn().mockResolvedValue({ results: [{ id: 1, kind: 'group' }] }),
+    getUnreadCount: vi.fn().mockResolvedValue({ unread_count: 0, by_conversation: {} }),
+    listMessages: vi.fn().mockResolvedValue({ results: [{ id: 2, conversation_id: 1, body: 'Visible message', created_at: '2026-07-31T10:00:00Z' }], next_cursor: 'signed-opaque-cursor' }),
+    listThread: vi.fn().mockResolvedValue({ results: [] }),
+    getReadStatus: vi.fn().mockResolvedValue({ all_read: false, delivered_count: 2 }),
+  };
+}
+function renderThread(api, { userId = 9 } = {}) {
+  return render(
+    <AuthContext.Provider value={{ user: { id: userId } }}>
+      <MessagingProvider api={api} activeConversationId={1}><Thread conversationId={1} /></MessagingProvider>
+    </AuthContext.Provider>,
+  );
+}
+
+describe('messaging Thread surfaces', () => {
+  let api;
+  beforeEach(() => { api = makeApi(); });
+  afterEach(cleanup);
+
+  it('uses the opaque message cursor and shows a rejected older page as an error', async () => {
+    api.listMessages.mockResolvedValueOnce({ results: [{ id: 2, conversation_id: 1, body: 'Visible message' }], next_cursor: 'signed-opaque-cursor' }).mockRejectedValueOnce(new Error('bad cursor'));
+    renderThread(api);
+    await screen.findByText('Visible message');
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingThread.LOAD_OLDER' }));
+    await screen.findByRole('alert');
+    expect(api.listMessages).toHaveBeenLastCalledWith(1, { cursor: 'signed-opaque-cursor' });
+    expect(screen.getByText('Visible message')).toBeTruthy();
+  });
+
+  it('renders deleted content as a redacted placeholder', () => {
+    render(<MessageBubble message={{ id: 4, body: 'Stale secret', deleted_at: '2026-07-31T10:00:00Z' }} />);
+    expect(screen.getByText('MessagingThread.DELETED')).toBeTruthy();
+    expect(screen.queryByText('Stale secret')).toBeNull();
+  });
+
+  it('renders aggregate read state and never exposes supplied recipient details for a direct conversation', async () => {
+    api.getReadStatus.mockResolvedValue({ all_read: false, delivered_count: 2, recipient_detail: [{ display_name: 'Private recipient' }] });
+    render(<MessagingProvider api={api} active={false}><ReadTicks messageId={2} conversation={{ id: 1, kind: 'direct' }} /></MessagingProvider>);
+    await screen.findByLabelText('MessagingReadTicks.DELIVERED:2');
+    expect(screen.queryByText('Private recipient')).toBeNull();
+  });
+
+  it('renders supplied recipient detail for a non-direct conversation (the permitted case)', async () => {
+    api.getReadStatus.mockResolvedValue({ all_read: false, delivered_count: 2, recipient_detail: [{ display_name: 'Visible recipient' }] });
+    render(<MessagingProvider api={api} active={false}><ReadTicks messageId={2} conversation={{ id: 1, kind: 'group' }} /></MessagingProvider>);
+    const tick = await screen.findByLabelText('MessagingReadTicks.DELIVERED:2');
+    fireEvent.mouseOver(tick);
+    await screen.findByText('Visible recipient');
+  });
+
+  it('only mounts ReadTicks (and its REST call) for the current user\'s own messages, not every message in the timeline', async () => {
+    api.listMessages.mockResolvedValue({
+      results: [
+        { id: 2, conversation_id: 1, body: 'Mine', created_at: '2026-07-31T10:00:00Z', sender: { id: 9 } },
+        { id: 3, conversation_id: 1, body: 'Theirs', created_at: '2026-07-31T10:01:00Z', sender: { id: 42 } },
+      ],
+      next_cursor: null,
+    });
+    renderThread(api, { userId: 9 });
+    await screen.findByText('Mine');
+    await screen.findByText('Theirs');
+    await waitFor(() => expect(api.getReadStatus).toHaveBeenCalledTimes(1));
+    expect(api.getReadStatus).toHaveBeenCalledWith(2);
+  });
+
+  it('does not mount ReadTicks (or fire a REST call) for a still-pending optimistic own message', async () => {
+    api.listMessages.mockResolvedValue({
+      results: [{ id: 'local-r9', conversation_id: 1, body: 'Sending...', created_at: '2026-07-31T10:00:00Z', sender: { id: 9 }, status: 'pending', client_request_id: 'r9' }],
+      next_cursor: null,
+    });
+    renderThread(api, { userId: 9 });
+    await screen.findByText('Sending...');
+    expect(api.getReadStatus).not.toHaveBeenCalled();
+  });
+
+  it('mounts Thread and ReadTicks independently', async () => {
+    renderThread(api);
+    await screen.findByLabelText('MessagingThread.TIMELINE');
+    cleanup();
+    render(<MessagingProvider api={api} active={false}><ReadTicks messageId={2} conversation={{ id: 1, kind: 'group' }} /></MessagingProvider>);
+    await waitFor(() => expect(screen.getByLabelText('MessagingReadTicks.DELIVERED:2')).toBeTruthy());
+  });
+});

package/tests/messagingApi.test.js

@@ -0,0 +1,32 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const client = vi.hoisted(() => ({ get: vi.fn(), post: vi.fn(), patch: vi.fn(), delete: vi.fn() }));
+vi.mock('../src/auth/apiClient', () => ({ default: client }));
+
+import * as api from '../src/messaging/api';
+
+const response = { data: { ok: true } };
+beforeEach(() => { vi.clearAllMocks(); Object.values(client).forEach((method) => method.mockResolvedValue(response)); });
+
+describe('messaging API contract', () => {
+  it('uses the published conversations and message routes', async () => {
+    await api.listConversations({ scope_kind: 'container', cursor: 'opaque' });
+    await api.createDirectConversation({ target_user_id: 8 });
+    await api.createGroupConversation({ title: 'Group' }); await api.createBroadcastConversation({}); await api.createManagedConversation({}); await api.createObjectThreadConversation({});
+    await api.getConversationConfig(1); await api.patchConversationConfig(1, {}); await api.archiveConversation(1, true); await api.patchConversationPreferences(1, {});
+    await api.listMessages(1, { cursor: 'opaque' }); await api.createMessage(1, { body: 'x' }, { idempotencyKey: 'key' }); await api.uploadAttachments(1, new FormData()); await api.createPoll(1, {});
+    expect(client.get).toHaveBeenCalledWith('/api/messaging/conversations/', { params: { scope_kind: 'container', cursor: 'opaque' } });
+    expect(client.post).toHaveBeenCalledWith('/api/messaging/conversations/direct/', { target_user_id: 8 });
+    expect(client.post).toHaveBeenCalledWith('/api/messaging/conversations/1/messages/', { body: 'x' }, { headers: { 'Idempotency-Key': 'key' } });
+    expect(client.get).toHaveBeenCalledWith('/api/messaging/conversations/1/messages/', { params: { cursor: 'opaque' } });
+  });
+
+  it('uses the published detail, receipt, poll and attachment routes', async () => {
+    await api.getMessage(2); await api.patchMessage(2, {}); await api.deleteMessage(2); await api.addReaction(2, '👍'); await api.removeReaction(2, '👍');
+    await api.listThread(2, { cursor: 'opaque' }); await api.markThreadRead(2); await api.markConversationRead(3); await api.getReadStatus(2); await api.votePoll(4, [5]); await api.closePoll(4); await api.getAttachment(6); await api.getAttachmentThumbnail(6); await api.getUnreadCount();
+    expect(client.delete).toHaveBeenCalledWith('/api/messaging/messages/2/reactions/%F0%9F%91%8D/');
+    expect(client.get).toHaveBeenCalledWith('/api/messaging/messages/2/thread/', { params: { cursor: 'opaque' } });
+    expect(client.post).toHaveBeenCalledWith('/api/messaging/conversations/3/read/', {});
+    expect(client.get).toHaveBeenCalledWith('/api/messaging/unread-count/');
+  });
+});