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

package/src/messaging/Composer.jsx

@@ -0,0 +1,110 @@
+import { Alert, Button, Checkbox, Dialog, DialogActions, DialogContent, DialogTitle, FormControlLabel, IconButton, Stack, TextField, Typography } from '@mui/material';
+import AttachFileIcon from '@mui/icons-material/AttachFile';
+import CampaignOutlinedIcon from '@mui/icons-material/CampaignOutlined';
+import PollOutlinedIcon from '@mui/icons-material/PollOutlined';
+import { useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { extractApiErrorMessage, useMessaging } from './MessagingProvider';
+
+function newRequestId() { return globalThis.crypto?.randomUUID?.() || `message-${Date.now()}-${Math.random().toString(36).slice(2)}`; }
+
+/**
+ * A provider-backed, independently mountable REST composer.
+ *
+ * `allowAnnouncement` and `linkTarget`: whether announcement composing (jg's
+ * `AnnouncementDialog` — title + body + a deep-link target) is offered here at
+ * all is a host decision (the server enforces who may actually post one; the
+ * client only offers the affordance). `linkTarget`'s VALUE is inherently
+ * app-specific navigation context (jg pre-fills it from the currently open
+ * event-info section) that ucm cannot compute itself, so the host supplies it.
+ */
+export function Composer({ conversationId, replyTarget = null, onReplyTargetChange, allowAnnouncement = false, linkTarget }) {
+  const { t } = useTranslation();
+  const { sendMessage, sendAttachments, createConversationPoll } = useMessaging();
+  const [body, setBody] = useState('');
+  const [files, setFiles] = useState([]);
+  const [error, setError] = useState(null);
+  const [failed, setFailed] = useState(null);
+  const [sending, setSending] = useState(false);
+  const [pollOpen, setPollOpen] = useState(false);
+  const [pollQuestion, setPollQuestion] = useState('');
+  const [pollOptions, setPollOptions] = useState(['', '']);
+  const [allowMultiple, setAllowMultiple] = useState(false);
+  const [announcementOpen, setAnnouncementOpen] = useState(false);
+  const [announcementTitle, setAnnouncementTitle] = useState('');
+  const [announcementBody, setAnnouncementBody] = useState('');
+  const inputRef = useRef(null);
+  const submit = async (requestId = newRequestId(), retry = false) => {
+    if (!body.trim() && !files.length) return;
+    setSending(true); setError(null);
+    const payload = { kind: 'chat', body: body.trim() || undefined, reply_to: replyTarget?.id || undefined, client_request_id: requestId };
+    try {
+      if (files.length) {
+        const formData = new FormData();
+        files.forEach((file) => formData.append('files[]', file));
+        if (payload.body) formData.append('body', payload.body);
+        if (payload.reply_to) formData.append('reply_to', String(payload.reply_to));
+        formData.append('client_request_id', requestId);
+        await sendAttachments(conversationId, formData, { clientRequestId: requestId, retry, optimisticMessage: { body: payload.body, reply_to: payload.reply_to, attachments: files.map((file, index) => ({ id: `local-${requestId}-${index}`, filename: file.name, content_type: file.type })) } });
+      } else await sendMessage(conversationId, payload, { clientRequestId: requestId, retry });
+      setBody(''); setFiles([]); setFailed(null); onReplyTargetChange?.(null);
+    } catch (sendError) {
+      const message = extractApiErrorMessage(sendError);
+      setError(files.length ? t('MessagingComposer.UPLOAD_ERROR', { message }) : t('MessagingComposer.SEND_ERROR', { message }));
+      setFailed({ requestId, retry: true });
+    } finally { setSending(false); }
+  };
+  const submitPoll = async () => {
+    const options = pollOptions.map((option) => option.trim()).filter(Boolean);
+    if (!pollQuestion.trim() || options.length < 2) { setError(t('MessagingPoll.CREATE_VALIDATION')); return; }
+    setSending(true); setError(null);
+    try {
+      await createConversationPoll(conversationId, { question: pollQuestion.trim(), options, allow_multiple: allowMultiple }, { clientRequestId: newRequestId() });
+      setPollQuestion(''); setPollOptions(['', '']); setAllowMultiple(false); setPollOpen(false);
+    } catch (pollError) { setError(t('MessagingPoll.CREATE_ERROR', { message: extractApiErrorMessage(pollError) })); } finally { setSending(false); }
+  };
+  const submitAnnouncement = async () => {
+    if (!announcementTitle.trim()) { setError(t('MessagingAnnouncement.VALIDATION')); return; }
+    setSending(true); setError(null);
+    const requestId = newRequestId();
+    try {
+      await sendMessage(conversationId, {
+        kind: 'announcement',
+        title: announcementTitle.trim(),
+        body: announcementBody.trim() || undefined,
+        link_target: linkTarget || undefined,
+        client_request_id: requestId,
+      }, { clientRequestId: requestId });
+      setAnnouncementTitle(''); setAnnouncementBody(''); setAnnouncementOpen(false);
+    } catch (announcementError) { setError(t('MessagingAnnouncement.ERROR', { message: extractApiErrorMessage(announcementError) })); } finally { setSending(false); }
+  };
+  return <Stack component="form" spacing={1} onSubmit={(event) => { event.preventDefault(); submit(); }} aria-label={t('MessagingComposer.LABEL')}>
+    {replyTarget && <Alert severity="info" onClose={() => onReplyTargetChange?.(null)}>{t('MessagingComposer.REPLYING_TO', { sender: replyTarget.sender?.display_name || t('MessagingThread.UNKNOWN_SENDER') })}</Alert>}
+    {error && <Alert severity="error" role="alert">{error}</Alert>}
+    {files.length > 0 && <Typography variant="caption">{t('MessagingComposer.FILES_SELECTED', { count: files.length })}</Typography>}
+    <Stack direction="row" spacing={1} alignItems="flex-end">
+      <input ref={inputRef} hidden type="file" multiple onChange={(event) => setFiles(Array.from(event.target.files || []))} />
+      <IconButton type="button" aria-label={t('MessagingComposer.ADD_ATTACHMENT')} onClick={() => inputRef.current?.click()}><AttachFileIcon /></IconButton>
+      <IconButton type="button" aria-label={t('MessagingPoll.CREATE')} onClick={() => setPollOpen(true)}><PollOutlinedIcon /></IconButton>
+      {allowAnnouncement && <IconButton type="button" aria-label={t('MessagingAnnouncement.CREATE')} onClick={() => setAnnouncementOpen(true)}><CampaignOutlinedIcon /></IconButton>}
+      <TextField fullWidth multiline minRows={2} value={body} onChange={(event) => setBody(event.target.value)} label={t('MessagingComposer.MESSAGE')} disabled={sending} />
+      <Button type="submit" variant="contained" disabled={sending || (!body.trim() && !files.length)}>{t('MessagingComposer.SEND')}</Button>
+    </Stack>
+    {failed && <Button type="button" onClick={() => submit(failed.requestId, true)} disabled={sending}>{t('MessagingComposer.RETRY')}</Button>}
+    <Dialog open={pollOpen} onClose={() => !sending && setPollOpen(false)} fullWidth maxWidth="sm">
+      <DialogTitle>{t('MessagingPoll.CREATE')}</DialogTitle><DialogContent><Stack spacing={1} sx={{ pt: 1 }}>
+        <TextField label={t('MessagingPoll.QUESTION')} value={pollQuestion} onChange={(event) => setPollQuestion(event.target.value)} autoFocus />
+        {pollOptions.map((option, index) => <TextField key={index} label={t('MessagingPoll.OPTION', { count: index + 1 })} value={option} onChange={(event) => setPollOptions((current) => current.map((value, optionIndex) => optionIndex === index ? event.target.value : value))} />)}
+        <Button type="button" onClick={() => setPollOptions((current) => [...current, ''])}>{t('MessagingPoll.ADD_OPTION')}</Button>
+        <FormControlLabel control={<Checkbox checked={allowMultiple} onChange={(event) => setAllowMultiple(event.target.checked)} />} label={t('MessagingPoll.ALLOW_MULTIPLE')} />
+      </Stack></DialogContent><DialogActions><Button onClick={() => setPollOpen(false)}>{t('MessagingPoll.CANCEL')}</Button><Button variant="contained" onClick={submitPoll} disabled={sending}>{t('MessagingPoll.CREATE')}</Button></DialogActions>
+    </Dialog>
+    {allowAnnouncement && <Dialog open={announcementOpen} onClose={() => !sending && setAnnouncementOpen(false)} fullWidth maxWidth="sm">
+      <DialogTitle>{t('MessagingAnnouncement.CREATE')}</DialogTitle><DialogContent><Stack spacing={1} sx={{ pt: 1 }}>
+        <TextField label={t('MessagingAnnouncement.TITLE')} value={announcementTitle} onChange={(event) => setAnnouncementTitle(event.target.value)} autoFocus />
+        <TextField label={t('MessagingAnnouncement.BODY')} value={announcementBody} onChange={(event) => setAnnouncementBody(event.target.value)} multiline minRows={2} />
+      </Stack></DialogContent><DialogActions><Button onClick={() => setAnnouncementOpen(false)}>{t('MessagingAnnouncement.CANCEL')}</Button><Button variant="contained" onClick={submitAnnouncement} disabled={sending}>{t('MessagingAnnouncement.SEND')}</Button></DialogActions>
+    </Dialog>}
+  </Stack>;
+}

package/src/messaging/ConversationLaunchers.jsx

@@ -0,0 +1,51 @@
+import { useEffect, useRef, useState } from 'react';
+import { Alert, Button, Stack } from '@mui/material';
+import { useTranslation } from 'react-i18next';
+
+import { useMessaging } from './MessagingProvider';
+
+/**
+ * Host apps provide launchable scopes. This component owns the REST transition
+ * that turns one into a normalized conversation, but deliberately does not
+ * discover groups itself: that is app-specific scope-picker data.
+ */
+export function ConversationLaunchers({ groupLaunchers = [], broadcastLauncher, autoOpenBroadcast = false, onOpen }) {
+  const { t } = useTranslation();
+  const { openGroupConversation, openBroadcastConversation } = useMessaging();
+  const [error, setError] = useState(null);
+  const autoOpened = useRef(false);
+
+  const open = async (kind, payload) => {
+    setError(null);
+    try {
+      const conversation = kind === 'broadcast'
+        ? await openBroadcastConversation(payload)
+        : await openGroupConversation(payload);
+      onOpen?.(conversation);
+    } catch {
+      setError(t('MessagingLaunchers.OPEN_ERROR'));
+    }
+  };
+
+  useEffect(() => {
+    if (!autoOpenBroadcast || !broadcastLauncher || autoOpened.current) return;
+    autoOpened.current = true;
+    open('broadcast', broadcastLauncher.payload ?? broadcastLauncher);
+  }, [autoOpenBroadcast, broadcastLauncher]); // one intentional auto-open per mounted launcher
+
+  return (
+    <Stack spacing={1}>
+      {broadcastLauncher && !autoOpenBroadcast && (
+        <Button variant="outlined" onClick={() => open('broadcast', broadcastLauncher.payload ?? broadcastLauncher)}>
+          {broadcastLauncher.label || t('MessagingLaunchers.OPEN_BROADCAST')}
+        </Button>
+      )}
+      {groupLaunchers.map((launcher) => (
+        <Button key={launcher.id ?? launcher.label} variant="outlined" onClick={() => open('group', launcher.payload ?? launcher)}>
+          {launcher.label || t('MessagingLaunchers.OPEN_GROUP')}
+        </Button>
+      ))}
+      {error && <Alert severity="error">{error}</Alert>}
+    </Stack>
+  );
+}

package/src/messaging/ConversationList.jsx

@@ -0,0 +1,78 @@
+import { useMemo, useState } from 'react';
+import { Archive, Campaign, Groups, MoreVert, NotificationsOff, Person } from '@mui/icons-material';
+import { Badge, Box, Button, CircularProgress, IconButton, List, ListItemButton, ListItemText, Menu, MenuItem, Stack, Typography } from '@mui/material';
+import { useTranslation } from 'react-i18next';
+
+import { useMessaging } from './MessagingProvider';
+import { ConversationLaunchers } from './ConversationLaunchers';
+
+function titleOf(conversation, t) { return conversation.title || conversation.other_user?.display_name || conversation.other_user?.username || t('MessagingList.UNTITLED'); }
+function ordered(conversations) {
+  return [...conversations].sort((left, right) => new Date(right.last_message_at || 0) - new Date(left.last_message_at || 0));
+}
+// jg's ConversationList renders a distinct icon per conversation kind so a
+// user can identify type/person at a glance (getConversationAvatar); that
+// glanceable identification is a feature, not layout, so it's reproduced
+// here rather than left as a generic archive-status glyph.
+function KindIcon({ conversation }) {
+  if (conversation.kind === 'broadcast') return <Campaign fontSize="small" />;
+  if (conversation.kind === 'group' || conversation.kind === 'managed' || conversation.kind === 'object_thread') return <Groups fontSize="small" />;
+  return <Person fontSize="small" />;
+}
+
+/** A standalone, provider-backed list; scope picker metadata is supplied as launcher props. */
+export function ConversationList({ onOpen, groupLaunchers, broadcastLauncher, autoOpenBroadcast = false, includeArchived = false }) {
+  const { t } = useTranslation();
+  const { cache, activeConversationId, loadMoreConversations, setConversationArchived, setConversationPreferences } = useMessaging();
+  const [menuConversation, setMenuConversation] = useState(null);
+  const [menuAnchor, setMenuAnchor] = useState(null);
+  const [loadingMore, setLoadingMore] = useState(false);
+  const [error, setError] = useState(null);
+  const conversations = useMemo(() => ordered(Object.values(cache.conversations).filter((item) => includeArchived || !item.archived_at && !item.archived)), [cache.conversations, includeArchived]);
+  const unreadFor = (conversation) => conversation.unread_count ?? cache.unread.by_conversation?.[conversation.id] ?? 0;
+  // Once opened, the broadcast conversation becomes a normal, recency-sorted
+  // row with real unread/preview state — hide the static launcher so it isn't
+  // shown twice (button + list row) with the button's stale, unread-less copy.
+  const broadcastAlreadyOpened = useMemo(() => Object.values(cache.conversations).some((item) => item.kind === 'broadcast'), [cache.conversations]);
+
+  const loadMore = async () => {
+    setLoadingMore(true); setError(null);
+    try { await loadMoreConversations(); } catch { setError(t('MessagingList.LOAD_ERROR')); } finally { setLoadingMore(false); }
+  };
+  const closeMenu = () => { setMenuConversation(null); setMenuAnchor(null); };
+  const archive = async () => {
+    try { await setConversationArchived(menuConversation.id, true); } catch { setError(t('MessagingList.ARCHIVE_ERROR')); }
+    closeMenu();
+  };
+  const toggleMute = async () => {
+    try { await setConversationPreferences(menuConversation.id, { muted: !menuConversation.muted }); } catch { setError(t('MessagingList.PREFERENCES_ERROR')); }
+    closeMenu();
+  };
+
+  return (
+    <Stack spacing={1}>
+      <ConversationLaunchers groupLaunchers={groupLaunchers} broadcastLauncher={broadcastAlreadyOpened ? null : broadcastLauncher} autoOpenBroadcast={autoOpenBroadcast && !broadcastAlreadyOpened} onOpen={onOpen} />
+      {error && <Typography color="error" role="alert">{error}</Typography>}
+      {!conversations.length ? <Box sx={{ py: 3, textAlign: 'center' }}><Typography color="text.secondary">{t('MessagingList.EMPTY')}</Typography></Box> : (
+        <List disablePadding aria-label={t('MessagingList.LABEL')}>
+          {conversations.map((conversation) => {
+            const unread = unreadFor(conversation);
+            const archived = Boolean(conversation.archived || conversation.archived_at);
+            return <ListItemButton key={conversation.id} selected={conversation.id === activeConversationId} onClick={() => onOpen?.(conversation)} sx={{ minHeight: 64, opacity: archived ? 0.6 : 1 }}>
+              <Badge color="error" badgeContent={unread || null} max={99} sx={{ mr: 2 }}>
+                {archived ? <Archive fontSize="small" color="disabled" /> : <KindIcon conversation={conversation} />}
+              </Badge>
+              <ListItemText primary={titleOf(conversation, t)} secondary={conversation.last_message?.body || t('MessagingList.NO_MESSAGES')} primaryTypographyProps={{ fontWeight: unread ? 700 : 400, noWrap: true }} secondaryTypographyProps={{ noWrap: true }} />
+              <IconButton aria-label={t('MessagingList.ACTIONS')} onClick={(event) => { event.stopPropagation(); setMenuAnchor(event.currentTarget); setMenuConversation(conversation); }}><MoreVert /></IconButton>
+            </ListItemButton>;
+          })}
+        </List>
+      )}
+      {cache.cursors.conversations && <Button onClick={loadMore} disabled={loadingMore}>{loadingMore ? <CircularProgress size={18} /> : t('MessagingList.LOAD_MORE')}</Button>}
+      <Menu anchorEl={menuAnchor} open={Boolean(menuConversation)} onClose={closeMenu}>
+        <MenuItem onClick={toggleMute}><NotificationsOff fontSize="small" sx={{ mr: 1 }} />{menuConversation?.muted ? t('MessagingList.UNMUTE') : t('MessagingList.MUTE')}</MenuItem>
+        <MenuItem onClick={archive}><Archive fontSize="small" sx={{ mr: 1 }} />{t('MessagingList.ARCHIVE')}</MenuItem>
+      </Menu>
+    </Stack>
+  );
+}

package/src/messaging/MessageBubble.jsx

@@ -0,0 +1,37 @@
+import { Button, Paper, Stack, Typography } from '@mui/material';
+import { useTranslation } from 'react-i18next';
+import { AttachmentList } from './AttachmentList';
+import { ReactionBar } from './ReactionBar';
+import { PollCard } from './PollCard';
+
+function senderName(message) {
+  return message.sender?.display_name || message.sender?.username || message.sender_name || message.sender?.name;
+}
+
+/** Provider-backed timeline collaborator; it deliberately has no mutation controls. */
+export function MessageBubble({ message, replyTo, onReply, children }) {
+  const { t } = useTranslation();
+  const deleted = Boolean(message.deleted_at);
+  const attachments = message.attachments || [];
+  return (
+    <Paper component="article" variant="outlined" sx={{ p: 1.25, maxWidth: 'min(100%, 680px)' }} aria-label={t('MessagingThread.MESSAGE')}>
+      <Stack spacing={0.75}>
+        {replyTo && <Typography variant="caption" color="text.secondary">{t('MessagingThread.REPLY_TO', { sender: senderName(replyTo) || t('MessagingThread.UNKNOWN_SENDER') })}</Typography>}
+        <Stack direction="row" spacing={1} alignItems="baseline">
+          <Typography variant="subtitle2">{senderName(message) || t('MessagingThread.UNKNOWN_SENDER')}</Typography>
+          {message.created_at && <Typography variant="caption" color="text.secondary">{new Date(message.created_at).toLocaleString()}</Typography>}
+          {message.edited_at && !deleted && <Typography variant="caption" color="text.secondary">{t('MessagingThread.EDITED')}</Typography>}
+        </Stack>
+        {!deleted && message.kind === 'announcement' && message.title && <Typography variant="subtitle1" fontWeight={700}>{message.title}</Typography>}
+        <Typography sx={{ whiteSpace: 'pre-wrap' }}>{deleted ? t('MessagingThread.DELETED') : (message.kind === 'announcement' ? message.body : (message.body || message.title)) || ''}</Typography>
+        {!deleted && <Stack spacing={0.75}>
+          {attachments.length > 0 && <AttachmentList attachments={attachments} />}
+          <ReactionBar message={message} />
+          {message.poll && <PollCard message={message} />}
+        </Stack>}
+        {!deleted && onReply && <Button type="button" size="small" onClick={() => onReply(message)}>{t('MessagingThread.REPLY')}</Button>}
+        {children}
+      </Stack>
+    </Paper>
+  );
+}

package/src/messaging/MessagingProvider.jsx

@@ -0,0 +1,323 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useReducer, useRef } from 'react';
+
+import { AuthContext } from '../auth/AuthContext';
+import {
+  archiveConversation,
+  createBroadcastConversation,
+  createGroupConversation,
+  getReadStatus,
+  getUnreadCount,
+  listConversations,
+  listMessages,
+  listThread,
+  patchConversationPreferences,
+  createMessage,
+  uploadAttachments,
+  getAttachment,
+  getAttachmentThumbnail,
+  addReaction,
+  removeReaction,
+  createPoll,
+  votePoll,
+  closePoll,
+  getConversationConfig,
+  patchConversationConfig,
+} from './api';
+import { useRealtime } from '../notifications/realtime';
+
+const MessagingContext = createContext(null);
+export const MESSAGING_ENVELOPE = 'messaging';
+const EMPTY_CACHE = { conversations: {}, messages: {}, threads: {}, polls: {}, reactions: {}, receipts: {}, unread: { unread_count: 0, by_conversation: {} }, cursors: { conversations: null, messages: {}, threads: {} } };
+const DEFAULT_API = {
+  listConversations, listMessages, listThread, getReadStatus, getUnreadCount, archiveConversation,
+  patchConversationPreferences, createGroupConversation, createBroadcastConversation,
+  createMessage, uploadAttachments, getAttachment, getAttachmentThumbnail,
+  addReaction, removeReaction, createPoll, votePoll, closePoll, getConversationConfig, patchConversationConfig,
+};
+
+function idOf(item) { return item?.id ?? item?.conversation_id ?? item?.message_id ?? item?.poll_id; }
+function mergeById(slice, item) { const id = idOf(item); return id == null ? slice : { ...slice, [id]: { ...slice[id], ...item } }; }
+function resultsOf(response) { return response?.results || []; }
+function clientRequestIdOf(message) { return message?.client_request_id; }
+
+/**
+ * dcm's DRF validation errors aren't always {detail}: ConversationAttachmentView
+ * translates a rejected upload into a field-keyed {"files": [...]} body (the
+ * MSG-2 chunk-4 fix — see django-core-micha messaging/views.py), while other
+ * endpoints use {detail}. Check every shape a caller might actually receive
+ * before falling back to the generic axios error message.
+ */
+export function extractApiErrorMessage(error) {
+  const data = error?.response?.data;
+  if (typeof data?.detail === 'string') return data.detail;
+  if (typeof data?.message === 'string') return data.message;
+  if (Array.isArray(data?.files)) return data.files.join(' ');
+  if (data && typeof data === 'object') {
+    const firstArray = Object.values(data).find((value) => Array.isArray(value) && value.length);
+    if (firstArray) return firstArray.join(' ');
+  }
+  return error?.message;
+}
+
+function reconcileMessage(messages, message) {
+  const requestId = clientRequestIdOf(message);
+  const matchingEntry = requestId && Object.entries(messages).find(([, item]) => clientRequestIdOf(item) === requestId);
+  if (!matchingEntry) return mergeById(messages, message);
+  const [previousKey, previous] = matchingEntry;
+  const next = { ...messages };
+  delete next[previousKey];
+  const id = idOf(message) ?? previousKey;
+  next[id] = { ...previous, ...message, id: idOf(message) ?? previous.id, status: message.status || 'sent', error: null };
+  return next;
+}
+
+export function messagingReducer(state, action) {
+  switch (action.type) {
+    case 'conversationsLoaded': {
+      const conversations = action.results.reduce((next, item) => mergeById(next, item), state.conversations);
+      return { ...state, conversations, cursors: { ...state.cursors, conversations: action.nextCursor ?? null } };
+    }
+    case 'unreadLoaded': return { ...state, unread: action.unread || EMPTY_CACHE.unread };
+    case 'messagesLoaded': {
+      const messages = action.results.reduce((next, item) => mergeById(next, item), state.messages);
+      return { ...state, messages, cursors: { ...state.cursors, messages: { ...state.cursors.messages, [action.conversationId]: action.nextCursor ?? null } } };
+    }
+    case 'threadLoaded': {
+      const messages = action.results.reduce((next, item) => mergeById(next, item), state.messages);
+      return { ...state, messages, cursors: { ...state.cursors, threads: { ...state.cursors.threads, [action.rootId]: action.nextCursor ?? null } } };
+    }
+    case 'conversationUpsert': return { ...state, conversations: mergeById(state.conversations, action.conversation) };
+    case 'messageOptimistic': return { ...state, messages: mergeById(state.messages, action.message) };
+    case 'messageReconciled': return { ...state, messages: reconcileMessage(state.messages, action.message) };
+    case 'messageFailed': {
+      const matching = Object.entries(state.messages).find(([, item]) => clientRequestIdOf(item) === action.clientRequestId);
+      if (!matching) return state;
+      const [key, message] = matching;
+      return { ...state, messages: { ...state.messages, [key]: { ...message, status: 'error', error: action.error } } };
+    }
+    case 'messagePatched': return { ...state, messages: mergeById(state.messages, action.message) };
+    case 'frame': return applyFrame(state, action.frame);
+    default: return state;
+  }
+}
+
+export function applyFrame(state, frame) {
+  const payload = frame.message || frame.conversation || frame.participant || frame;
+  const conversationId = frame.conversation_id ?? payload.conversation_id;
+  if (frame.type === 'message') {
+    const message = { ...payload, conversation_id: conversationId };
+    return { ...state, messages: reconcileMessage(state.messages, message) };
+  }
+  if (frame.type === 'message_edited') return { ...state, messages: mergeById(state.messages, payload) };
+  if (frame.type === 'reaction') {
+    const messageId = frame.message_id ?? payload.message_id;
+    const previous = state.messages[messageId] || { id: messageId };
+    return { ...state, messages: mergeById(state.messages, { ...previous, reactions: payload.reactions || frame.reactions || previous.reactions || [] }) };
+  }
+  if (frame.type === 'poll_updated') {
+    const messageId = frame.message_id ?? payload.message_id;
+    const previous = state.messages[messageId] || { id: messageId };
+    const poll = payload.poll || frame.poll || payload;
+    return { ...state, messages: mergeById(state.messages, { ...previous, poll }), polls: mergeById(state.polls, poll) };
+  }
+  if (frame.type === 'message_deleted') {
+    const previous = state.messages[frame.message_id] || {};
+    return { ...state, messages: { ...state.messages, [frame.message_id]: { ...previous, id: frame.message_id, deleted_at: frame.deleted_at, deleted_by: frame.deleted_by, body: null, title: null, link_target: null } } };
+  }
+  if (frame.type === 'conversation_upsert') return { ...state, conversations: mergeById(state.conversations, payload) };
+  // conversation_archived/participant_changed: the design doc names these frame
+  // types but doesn't pin their exact payload shape. Treating them as merging
+  // onto the conversation record (participant-local fields folded flat, an
+  // `archived` flag set) is this chunk's best-effort reading, not a confirmed
+  // contract — re-verify against dcm's actual WS payload once available, per
+  // the WO's "shape fixtures from the design doc, not from imagination" caution.
+  if (frame.type === 'conversation_archived') return { ...state, conversations: mergeById(state.conversations, { ...payload, id: conversationId, archived: true }) };
+  if (frame.type === 'participant_changed') return { ...state, conversations: mergeById(state.conversations, { ...payload, id: conversationId }) };
+  return state;
+}
+
+export function MessagingProvider({ children, filters = {}, activeConversationId = null, api = DEFAULT_API, active = true }) {
+  const { subscribe, onReconnect } = useRealtime();
+  const { user } = useContext(AuthContext) || {};
+  const [cache, dispatch] = useReducer(messagingReducer, EMPTY_CACHE);
+  const activeIdRef = useRef(activeConversationId);
+  const seenEventsRef = useRef(new Set());
+  const filtersRef = useRef(filters);
+  activeIdRef.current = activeConversationId;
+  filtersRef.current = filters;
+
+  const refreshConversations = useCallback(async () => {
+    const response = await api.listConversations(filtersRef.current);
+    dispatch({ type: 'conversationsLoaded', results: resultsOf(response), nextCursor: response?.next_cursor });
+    return response;
+  }, [api]);
+  const refreshUnread = useCallback(async () => {
+    const unread = await api.getUnreadCount();
+    dispatch({ type: 'unreadLoaded', unread });
+    return unread;
+  }, [api]);
+  const refreshThread = useCallback(async (conversationId = activeIdRef.current, { cursor } = {}) => {
+    if (conversationId == null) return null;
+    const response = await api.listMessages(conversationId, ...(cursor ? [{ cursor }] : []));
+    dispatch({ type: 'messagesLoaded', conversationId, results: resultsOf(response), nextCursor: response?.next_cursor });
+    return response;
+  }, [api]);
+  const loadMoreMessages = useCallback((conversationId = activeIdRef.current) => {
+    const cursor = cache.cursors.messages[conversationId];
+    return cursor ? refreshThread(conversationId, { cursor }) : Promise.resolve(null);
+  }, [cache.cursors.messages, refreshThread]);
+  const loadThreadReplies = useCallback(async (rootId, { cursor } = {}) => {
+    const response = await api.listThread(rootId, { cursor });
+    dispatch({ type: 'threadLoaded', rootId, results: resultsOf(response), nextCursor: response?.next_cursor });
+    return response;
+  }, [api]);
+  const getMessageReadStatus = useCallback((messageId) => api.getReadStatus(messageId), [api]);
+  const loadMoreConversations = useCallback(async () => {
+    const cursor = cache.cursors.conversations;
+    if (!cursor) return null;
+    const response = await api.listConversations({ ...filtersRef.current, cursor });
+    dispatch({ type: 'conversationsLoaded', results: resultsOf(response), nextCursor: response?.next_cursor });
+    return response;
+  }, [api, cache.cursors.conversations]);
+  const updateConversation = useCallback((conversation) => {
+    dispatch({ type: 'conversationUpsert', conversation });
+    return conversation;
+  }, []);
+  const setConversationArchived = useCallback(async (conversationId, archived) => {
+    const conversation = await api.archiveConversation(conversationId, archived);
+    return updateConversation({ ...conversation, id: conversation?.id ?? conversationId, archived: Boolean(archived) });
+  }, [api, updateConversation]);
+  const setConversationPreferences = useCallback(async (conversationId, patch) => {
+    const conversation = await api.patchConversationPreferences(conversationId, patch);
+    return updateConversation({ ...conversation, id: conversation?.id ?? conversationId, ...patch });
+  }, [api, updateConversation]);
+  const openGroupConversation = useCallback(async (payload) => {
+    const conversation = await api.createGroupConversation(payload);
+    return updateConversation(conversation);
+  }, [api, updateConversation]);
+  const openBroadcastConversation = useCallback(async (payload) => {
+    const conversation = await api.createBroadcastConversation(payload);
+    return updateConversation(conversation);
+  }, [api, updateConversation]);
+  const sendMessage = useCallback(async (conversationId, payload, { clientRequestId, retry = false } = {}) => {
+    const requestId = clientRequestId || payload.client_request_id;
+    const optimistic = {
+      id: `local-${requestId}`,
+      conversation_id: conversationId,
+      kind: payload.kind || 'chat',
+      body: payload.body || '',
+      title: payload.title || null,
+      link_target: payload.link_target || null,
+      reply_to: payload.reply_to || null,
+      client_request_id: requestId,
+      created_at: new Date().toISOString(),
+      status: 'pending',
+      sender: user ? { id: user.id, display_name: user.display_name || user.username } : undefined,
+      ...(retry ? {} : {}),
+    };
+    if (!retry) dispatch({ type: 'messageOptimistic', message: optimistic });
+    else dispatch({ type: 'messageReconciled', message: { ...optimistic, status: 'pending', error: null } });
+    try {
+      const message = await api.createMessage(conversationId, { ...payload, client_request_id: requestId }, { idempotencyKey: requestId });
+      dispatch({ type: 'messageReconciled', message: { ...message, conversation_id: message?.conversation_id ?? conversationId, client_request_id: message?.client_request_id ?? requestId } });
+      return message;
+    } catch (error) {
+      dispatch({ type: 'messageFailed', clientRequestId: requestId, error: extractApiErrorMessage(error) });
+      throw error;
+    }
+  }, [api, user]);
+  const sendAttachments = useCallback(async (conversationId, formData, { clientRequestId, optimisticMessage, retry = false } = {}) => {
+    const optimistic = {
+      id: `local-${clientRequestId}`, conversation_id: conversationId, kind: 'chat', body: optimisticMessage?.body || '',
+      reply_to: optimisticMessage?.reply_to || null, client_request_id: clientRequestId, created_at: new Date().toISOString(), status: 'pending',
+      sender: user ? { id: user.id, display_name: user.display_name || user.username } : undefined,
+      attachments: optimisticMessage?.attachments || [],
+    };
+    if (!retry) dispatch({ type: 'messageOptimistic', message: optimistic });
+    else dispatch({ type: 'messageReconciled', message: { ...optimistic, status: 'pending', error: null } });
+    try {
+      const message = await api.uploadAttachments(conversationId, formData, { idempotencyKey: clientRequestId });
+      dispatch({ type: 'messageReconciled', message: { ...message, conversation_id: message?.conversation_id ?? conversationId, client_request_id: message?.client_request_id ?? clientRequestId } });
+      return message;
+    } catch (error) {
+      dispatch({ type: 'messageFailed', clientRequestId, error: extractApiErrorMessage(error) });
+      throw error;
+    }
+  }, [api, user]);
+  const patchMessage = useCallback((message) => dispatch({ type: 'messagePatched', message }), []);
+  const toggleReaction = useCallback(async (messageId, emoji, active) => {
+    const message = cache.messages[messageId] || { id: messageId };
+    const reactions = message.reactions || [];
+    const current = reactions.find((reaction) => reaction.emoji === emoji);
+    const nextReactions = active
+      ? reactions.map((reaction) => reaction.emoji === emoji ? { ...reaction, reacted: false, count: Math.max(0, (reaction.count || 1) - 1) } : reaction).filter((reaction) => reaction.count !== 0)
+      : current
+        ? reactions.map((reaction) => reaction.emoji === emoji ? { ...reaction, reacted: true, count: (reaction.count || 0) + 1 } : reaction)
+        : [...reactions, { emoji, count: 1, reacted: true }];
+    patchMessage({ ...message, reactions: nextReactions });
+    try {
+      const result = active ? await api.removeReaction(messageId, emoji) : await api.addReaction(messageId, emoji);
+      patchMessage({ ...message, ...(result?.message || result), reactions: result?.reactions || result?.message?.reactions || nextReactions });
+      return result;
+    } catch (error) { patchMessage(message); throw error; }
+  }, [api, cache.messages, patchMessage]);
+  const createConversationPoll = useCallback(async (conversationId, payload, { clientRequestId } = {}) => {
+    const poll = await api.createPoll(conversationId, { ...payload, client_request_id: clientRequestId }, { idempotencyKey: clientRequestId });
+    const message = poll?.message || poll;
+    if (message?.id != null) patchMessage({ ...message, conversation_id: message.conversation_id ?? conversationId, poll: message.poll || poll.poll || poll });
+    return poll;
+  }, [api, patchMessage]);
+  const castPollVote = useCallback(async (messageId, poll, optionIds) => {
+    const result = await api.votePoll(poll.id, optionIds);
+    const nextPoll = { ...poll, ...(result?.poll || result) };
+    patchMessage({ ...(cache.messages[messageId] || { id: messageId }), poll: nextPoll });
+    return result;
+  }, [api, cache.messages, patchMessage]);
+  const closeConversationPoll = useCallback(async (messageId, poll) => {
+    const result = await api.closePoll(poll.id);
+    const nextPoll = { ...poll, ...(result?.poll || result), closed_at: result?.poll?.closed_at || result?.closed_at || new Date().toISOString() };
+    patchMessage({ ...(cache.messages[messageId] || { id: messageId }), poll: nextPoll });
+    return result;
+  }, [api, cache.messages, patchMessage]);
+  const loadConversationConfig = useCallback((conversationId) => api.getConversationConfig(conversationId), [api]);
+  const saveConversationConfig = useCallback((conversationId, patch) => api.patchConversationConfig(conversationId, patch), [api]);
+  const refresh = useCallback(async () => Promise.all([refreshConversations(), refreshUnread(), refreshThread()]), [refreshConversations, refreshThread, refreshUnread]);
+
+  // `/api/messaging/` is authenticated-only (design §REST). Host apps mount
+  // MessagingProvider inside NotificationsProvider, which itself renders its
+  // children regardless of auth state — so without this gate a provider
+  // mounted before login completes fires three REST calls that spuriously
+  // 401. Defaults to true (matches chunk 1's existing tests/harness usage,
+  // which don't pass it); a host app gates it with `active={authenticated}`.
+  useEffect(() => { if (active) refresh().catch(() => {}); }, [active, refresh]);
+  useEffect(() => subscribe(MESSAGING_ENVELOPE, (frame) => {
+    if (frame.event_id && seenEventsRef.current.has(frame.event_id)) return;
+    if (frame.event_id) {
+      seenEventsRef.current.add(frame.event_id);
+      if (seenEventsRef.current.size > 500) seenEventsRef.current.delete(seenEventsRef.current.values().next().value);
+    }
+    dispatch({ type: 'frame', frame });
+  }), [subscribe]);
+  useEffect(() => {
+    if (!active || !onReconnect) return undefined;
+    return onReconnect(() => { refresh().catch(() => {}); });
+  }, [active, onReconnect, refresh]);
+
+  const value = useMemo(() => ({
+    cache, refresh, refreshConversations, refreshUnread, refreshThread, loadMoreMessages, loadThreadReplies, getMessageReadStatus, loadMoreConversations,
+    setConversationArchived, setConversationPreferences, openGroupConversation,
+    openBroadcastConversation, sendMessage, sendAttachments, toggleReaction, createConversationPoll, castPollVote, closeConversationPoll,
+    loadConversationConfig, saveConversationConfig, currentUser: user, getAttachment: api.getAttachment,
+    getAttachmentThumbnail: api.getAttachmentThumbnail, activeConversationId,
+  }), [cache, refresh, refreshConversations, refreshUnread, refreshThread, loadMoreMessages, loadThreadReplies, getMessageReadStatus, loadMoreConversations,
+    setConversationArchived, setConversationPreferences, openGroupConversation,
+    openBroadcastConversation, sendMessage, sendAttachments, toggleReaction, createConversationPoll, castPollVote, closeConversationPoll,
+    loadConversationConfig, saveConversationConfig, user, api.getAttachment, api.getAttachmentThumbnail, activeConversationId]);
+  return <MessagingContext.Provider value={value}>{children}</MessagingContext.Provider>;
+}
+
+export function useMessaging() {
+  const context = useContext(MessagingContext);
+  if (!context) throw new Error('useMessaging must be used within a MessagingProvider');
+  return context;
+}

package/src/messaging/MessagingScopeConfig.jsx

@@ -0,0 +1,24 @@
+import { Alert, Box, CircularProgress, FormControl, FormControlLabel, InputLabel, MenuItem, Select, Stack, Switch, Typography } from '@mui/material';
+import { useEffect, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { extractApiErrorMessage, useMessaging } from './MessagingProvider';
+
+/** Provider-backed scope configuration surface; hosts choose its placement and capability gate. */
+export function MessagingScopeConfig({ conversationId }) {
+  const { t } = useTranslation();
+  const { loadConversationConfig, saveConversationConfig } = useMessaging();
+  const [config, setConfig] = useState(null);
+  const [error, setError] = useState(null);
+  const [saving, setSaving] = useState(false);
+  useEffect(() => { let live = true; loadConversationConfig(conversationId).then((value) => live && setConfig(value)).catch((loadError) => live && setError(t('MessagingConfig.LOAD_ERROR', { message: extractApiErrorMessage(loadError) }))); return () => { live = false; }; }, [conversationId, loadConversationConfig, t]);
+  const update = async (patch) => { setSaving(true); setError(null); try { setConfig(await saveConversationConfig(conversationId, patch)); } catch (saveError) { setError(t('MessagingConfig.SAVE_ERROR', { message: extractApiErrorMessage(saveError) })); } finally { setSaving(false); } };
+  if (!config) return error
+    ? <Alert severity="error" role="alert">{error}</Alert>
+    : <Box aria-label={t('MessagingConfig.LOADING')} sx={{ display: 'flex', justifyContent: 'center', py: 4 }}><CircularProgress size={24} /></Box>;
+  return <Stack spacing={1} aria-label={t('MessagingConfig.LABEL')}><Typography variant="subtitle1">{t('MessagingConfig.TITLE')}</Typography>{error && <Alert severity="error" role="alert">{error}</Alert>}
+    <FormControl fullWidth size="small" disabled={saving}><InputLabel>{t('MessagingConfig.DM_POLICY')}</InputLabel><Select label={t('MessagingConfig.DM_POLICY')} value={config.dm_policy || 'all'} onChange={(event) => update({ dm_policy: event.target.value })}><MenuItem value="all">{t('MessagingConfig.DM_ALL')}</MenuItem><MenuItem value="within_shared_groups">{t('MessagingConfig.DM_SHARED')}</MenuItem><MenuItem value="team_only">{t('MessagingConfig.DM_TEAM')}</MenuItem></Select></FormControl>
+    <FormControlLabel control={<Switch checked={Boolean(config.group_chat_enabled)} disabled={saving} onChange={(event) => update({ group_chat_enabled: event.target.checked })} />} label={t('MessagingConfig.GROUP_ENABLED')} />
+    <FormControlLabel control={<Switch checked={Boolean(config.everyone_can_post)} disabled={saving || !config.group_chat_enabled} onChange={(event) => update({ everyone_can_post: event.target.checked })} />} label={t('MessagingConfig.EVERYONE_POSTS')} />
+  </Stack>;
+}