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

package/src/messaging/Thread.jsx

@@ -1,5 +1,5 @@
 import { Alert, Box, Button, CircularProgress, Divider, Stack, Typography } from '@mui/material';
-import { useCallback, useContext, useMemo, useRef, useState } from 'react';
+import { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 
 import { AuthContext } from '../auth/AuthContext';
@@ -8,6 +8,7 @@ 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)); }
+function replyToId(message) { return message.reply_to_id ?? message.reply_to; }
 // 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.
@@ -27,27 +28,57 @@ function canShowReadTicks(message, user) {
  * `getMessageReadStatus` REST calls a rendered timeline fires — one per own
  * message shown, not one per message in the conversation.
  */
-export function Thread({ conversationId, onReplyTargetChange }) {
+export function Thread({ conversationId, onReplyTargetChange, canModerateMessages = false, onAnnouncementLink }) {
   const { t } = useTranslation();
   const { user } = useContext(AuthContext) || {};
-  const { cache, loadMoreMessages, loadThreadReplies } = useMessaging();
+  const { cache, loadMoreMessages, loadThreadReplies, markConversationRead, markThreadRead } = useMessaging();
   const scrollRef = useRef(null);
+  const wasNearBottomRef = useRef(true);
+  const messageCountRef = useRef(0);
   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 conversationMessages = useMemo(() => chronological(Object.values(cache.messages).filter((message) => message.conversation_id === conversationId)), [cache.messages, conversationId]);
+  const roots = useMemo(() => chronological(Object.values(cache.messages).filter((message) => message.conversation_id === conversationId && !replyToId(message))), [cache.messages, conversationId]);
+
+  useEffect(() => { if (conversationId != null) markConversationRead(conversationId).catch(() => {}); }, [conversationId, markConversationRead]);
+  useEffect(() => { wasNearBottomRef.current = true; messageCountRef.current = 0; }, [conversationId]);
+  useEffect(() => {
+    if (replyingTo && cache.messages[replyingTo.id]?.deleted_at) {
+      setReplyingTo(null);
+      onReplyTargetChange?.(null);
+    }
+  }, [cache.messages, onReplyTargetChange, replyingTo]);
+  useEffect(() => {
+    const isNewMessage = conversationMessages.length > messageCountRef.current;
+    messageCountRef.current = conversationMessages.length;
+    if (!isNewMessage || !wasNearBottomRef.current || !scrollRef.current) return;
+    const timeline = scrollRef.current;
+    if (typeof timeline.scrollTo === 'function') timeline.scrollTo({ top: timeline.scrollHeight, behavior: 'smooth' });
+    else timeline.scrollTop = timeline.scrollHeight;
+  }, [conversationMessages]);
 
   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 onScroll = () => {
+    const timeline = scrollRef.current;
+    if (timeline) wasNearBottomRef.current = timeline.scrollHeight - timeline.scrollTop - timeline.clientHeight < 80;
+    if (timeline?.scrollTop === 0 && cache.cursors.messages[conversationId] && !loadingOlder) loadOlder();
+  };
   const reply = (message) => { setReplyingTo(message); onReplyTargetChange?.(message); };
+  const jumpToMessage = (messageId) => {
+    const target = [...(scrollRef.current?.querySelectorAll('[data-message-id]') || [])]
+      .find((element) => String(element.dataset.messageId) === String(messageId));
+    target?.scrollIntoView?.({ block: 'center', behavior: 'smooth' });
+  };
   const toggleReplies = async (root) => {
     if (!openThreads[root.id]) {
       try { await loadThreadReplies(root.id); } catch { setError(t('MessagingThread.REPLIES_ERROR')); return; }
+      markThreadRead(root.id).catch(() => {});
     }
     setOpenThreads((current) => ({ ...current, [root.id]: !current[root.id] }));
   };
@@ -59,10 +90,10 @@ export function Thread({ conversationId, onReplyTargetChange }) {
         {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>
+          const replies = chronological(Object.values(cache.messages).filter((item) => String(replyToId(item)) === String(message.id)));
+          return <Stack key={message.id} spacing={0.75}><MessageBubble message={message} conversation={conversation} onReply={reply} onJumpToMessage={jumpToMessage} onAnnouncementLink={onAnnouncementLink} canModerateMessages={canModerateMessages}>{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>}
+            {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} conversation={conversation} onReply={reply} onJumpToMessage={jumpToMessage} onAnnouncementLink={onAnnouncementLink} canModerateMessages={canModerateMessages}>{canShowReadTicks(item, user) && <ReadTicks messageId={item.id} conversation={conversation} />}</MessageBubble>)}</Stack>}
             <Divider /></Stack>;
         })}</Stack>
       </Box>

package/src/messaging/api.js

@@ -7,11 +7,12 @@ function data(response) {
   return response.data;
 }
 
-function requestConfig({ cursor, params, headers } = {}) {
+function requestConfig({ cursor, params, headers, onUploadProgress } = {}) {
   return {
     ...(params ? { params } : {}),
     ...(cursor ? { params: { ...(params || {}), cursor } } : {}),
     ...(headers ? { headers } : {}),
+    ...(onUploadProgress ? { onUploadProgress } : {}),
   };
 }
 
@@ -29,7 +30,7 @@ export function archiveConversation(conversationId, archived) { return apiClient
 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 uploadAttachments(conversationId, formData, { idempotencyKey, onUploadProgress } = {}) { return apiClient.post(`${conversationsUrl}${conversationId}/attachments/`, formData, requestConfig({ headers: idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : undefined, onUploadProgress })).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); }

package/src/messaging/composerImageCompression.js

@@ -0,0 +1,35 @@
+const MAX_IMAGE_BYTES = 2 * 1024 * 1024;
+const MAX_IMAGE_EDGE = 2560;
+
+function imageDimensions(file) {
+  return new Promise((resolve, reject) => {
+    const url = URL.createObjectURL(file);
+    const image = new Image();
+    image.onload = () => { URL.revokeObjectURL(url); resolve(image); };
+    image.onerror = () => { URL.revokeObjectURL(url); reject(new Error('Unable to decode image')); };
+    image.src = url;
+  });
+}
+
+function canvasBlob(canvas) {
+  return new Promise((resolve) => canvas.toBlob(resolve, 'image/jpeg', 0.85));
+}
+
+/** Compresses large images opportunistically; callers always receive a sendable file. */
+export async function compressImageForUpload(file) {
+  if (!file?.type?.startsWith('image/') || file.size <= MAX_IMAGE_BYTES) return file;
+  try {
+    const image = await imageDimensions(file);
+    const largestEdge = Math.max(image.naturalWidth || image.width, image.naturalHeight || image.height);
+    if (!largestEdge || largestEdge <= MAX_IMAGE_EDGE) return file;
+    const scale = MAX_IMAGE_EDGE / largestEdge;
+    const canvas = document.createElement('canvas');
+    canvas.width = Math.round((image.naturalWidth || image.width) * scale);
+    canvas.height = Math.round((image.naturalHeight || image.height) * scale);
+    canvas.getContext('2d')?.drawImage(image, 0, 0, canvas.width, canvas.height);
+    const blob = await canvasBlob(canvas);
+    return blob ? new File([blob], file.name.replace(/\.[^.]+$/, '') + '.jpg', { type: 'image/jpeg', lastModified: file.lastModified }) : file;
+  } catch {
+    return file;
+  }
+}

package/tests/Thread.test.jsx

@@ -61,7 +61,7 @@ describe('messaging Thread surfaces', () => {
     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);
+    fireEvent.click(tick);
     await screen.findByText('Visible recipient');
   });
 

package/tests/messagingChunk6.test.jsx

@@ -0,0 +1,109 @@
+// @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';
+
+let frameHandler;
+vi.mock('react-i18next', () => ({ useTranslation: () => ({ t: (key, options) => options?.count != null ? `${key}:${options.count}` : key, i18n: { language: 'en' } }) }));
+vi.mock('../src/notifications/realtime', () => ({ useRealtime: () => ({ subscribe: (_envelope, handler) => { frameHandler = handler; return () => {}; }, onReconnect: () => () => {} }) }));
+
+import { Composer } from '../src/messaging/Composer';
+import { ConversationList } from '../src/messaging/ConversationList';
+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(overrides = {}) {
+  return {
+    listConversations: vi.fn().mockResolvedValue({ results: [] }),
+    listMessages: vi.fn().mockResolvedValue({ results: [] }),
+    listThread: vi.fn().mockResolvedValue({ results: [] }),
+    getUnreadCount: vi.fn().mockResolvedValue({ unread_count: 0, by_conversation: {} }),
+    getReadStatus: vi.fn().mockResolvedValue({ all_read: false, delivered_count: 2 }),
+    markConversationRead: vi.fn().mockResolvedValue({}), markThreadRead: vi.fn().mockResolvedValue({}),
+    createPoll: vi.fn().mockResolvedValue({}),
+    ...overrides,
+  };
+}
+
+afterEach(() => { cleanup(); vi.useRealTimers(); vi.restoreAllMocks(); frameHandler = undefined; });
+
+describe('MSG-3b chunk 6', () => {
+  it('renders localized relative list timestamps for now, minutes, hours, and days', async () => {
+    vi.spyOn(Date, 'now').mockReturnValue(new Date('2026-07-31T12:00:00Z').getTime());
+    const api = makeApi({ listConversations: vi.fn().mockResolvedValue({ results: [
+      { id: 1, title: 'Now', last_message_at: '2026-07-31T11:59:50Z' },
+      { id: 2, title: 'Minutes', last_message_at: '2026-07-31T11:55:00Z' },
+      { id: 3, title: 'Hours', last_message_at: '2026-07-31T09:00:00Z' },
+      { id: 4, title: 'Days', last_message_at: '2026-07-29T12:00:00Z' },
+    ] }) });
+    render(<MessagingProvider api={api}><ConversationList /></MessagingProvider>);
+    await screen.findByText('Now');
+    expect(screen.getByText('now')).toBeTruthy();
+    expect(screen.getByText(/5m/)).toBeTruthy();
+    expect(screen.getByText(/3h/)).toBeTruthy();
+    expect(screen.getByText(/2d/)).toBeTruthy();
+  });
+
+  it('auto-scrolls only for active-conversation messages when the reader was near the bottom', async () => {
+    const api = makeApi({ listConversations: vi.fn().mockResolvedValue({ results: [{ id: 1, kind: 'group' }] }), listMessages: vi.fn().mockResolvedValue({ results: [{ id: 1, conversation_id: 1, body: 'First' }] }) });
+    render(<MessagingProvider api={api} activeConversationId={1}><Thread conversationId={1} /></MessagingProvider>);
+    const timeline = await screen.findByLabelText('MessagingThread.TIMELINE');
+    Object.defineProperties(timeline, { scrollHeight: { configurable: true, value: 1000 }, clientHeight: { configurable: true, value: 300 }, scrollTop: { configurable: true, writable: true, value: 690 } });
+    timeline.scrollTo = vi.fn();
+    fireEvent.scroll(timeline);
+    frameHandler({ type: 'message', conversation_id: 1, message: { id: 2, body: 'Near bottom' } });
+    await waitFor(() => expect(timeline.scrollTo).toHaveBeenCalledTimes(1));
+    timeline.scrollTo.mockClear(); timeline.scrollTop = 100;
+    fireEvent.scroll(timeline);
+    frameHandler({ type: 'message', conversation_id: 1, message: { id: 3, body: 'Reading history' } });
+    await screen.findByText('Reading history');
+    expect(timeline.scrollTo).not.toHaveBeenCalled();
+  });
+
+  it('renders announcement deep links only with a host handler and supplies its exact target', () => {
+    const onAnnouncementLink = vi.fn();
+    const message = { id: 3, kind: 'announcement', title: 'Notice', body: 'Read this', link_target: '/events/7' };
+    const bubble = (props) => <MessagingProvider api={makeApi()} active={false}><MessageBubble {...props} /></MessagingProvider>;
+    const view = render(bubble({ message, onAnnouncementLink }));
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingAnnouncement.OPEN_LINK' }));
+    expect(onAnnouncementLink).toHaveBeenCalledWith('/events/7');
+    view.rerender(bubble({ message }));
+    expect(screen.queryByRole('button', { name: 'MessagingAnnouncement.OPEN_LINK' })).toBeNull();
+    view.rerender(bubble({ message: { ...message, link_target: null }, onAnnouncementLink }));
+    expect(screen.queryByRole('button', { name: 'MessagingAnnouncement.OPEN_LINK' })).toBeNull();
+  });
+
+  it('shows senders for group messages and suppresses them for direct messages', () => {
+    const message = { id: 4, body: 'Hi', sender: { display_name: 'Ava' } };
+    const bubble = (conversation) => <MessagingProvider api={makeApi()} active={false}><MessageBubble message={message} conversation={conversation} /></MessagingProvider>;
+    const view = render(bubble({ kind: 'group' }));
+    expect(screen.getByText('Ava')).toBeTruthy();
+    view.rerender(bubble({ kind: 'direct' }));
+    expect(screen.queryByText('Ava')).toBeNull();
+  });
+
+  it('opens receipt recipients by click for non-direct conversations and never exposes direct details', async () => {
+    const api = makeApi({ getReadStatus: vi.fn().mockResolvedValue({ all_read: false, delivered_count: 2, recipient_detail: [{ display_name: 'Ava' }] }) });
+    const view = render(<MessagingProvider api={api} active={false}><ReadTicks messageId={7} conversation={{ kind: 'group' }} /></MessagingProvider>);
+    const detail = await screen.findByRole('button', { name: 'MessagingReadTicks.DELIVERED:2' });
+    fireEvent.click(detail);
+    expect(await screen.findByText('Ava')).toBeTruthy();
+    view.unmount();
+    render(<MessagingProvider api={api} active={false}><ReadTicks messageId={7} conversation={{ kind: 'direct' }} /></MessagingProvider>);
+    await screen.findByLabelText('MessagingReadTicks.DELIVERED:2');
+    expect(screen.queryByRole('button', { name: 'MessagingReadTicks.DELIVERED:2' })).toBeNull();
+    expect(screen.queryByText('Ava')).toBeNull();
+  });
+
+  it('caps poll composer options at ten without changing the existing two-option start', () => {
+    render(<MessagingProvider api={makeApi()} active={false}><Composer conversationId={1} /></MessagingProvider>);
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingPoll.CREATE' }));
+    const addOption = screen.getByRole('button', { name: 'MessagingPoll.ADD_OPTION' });
+    expect(screen.getAllByLabelText(/MessagingPoll.OPTION/)).toHaveLength(2);
+    for (let count = 0; count < 8; count += 1) fireEvent.click(addOption);
+    expect(screen.getAllByLabelText(/MessagingPoll.OPTION/)).toHaveLength(10);
+    expect(addOption.disabled).toBe(true);
+  });
+});

package/tests/messagingComposerChunk5.test.jsx

@@ -0,0 +1,110 @@
+// @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?.name ? `${key}:${options.name}` : key }) }));
+vi.mock('../src/notifications/realtime', () => ({ useRealtime: () => ({ subscribe: () => () => {}, onReconnect: () => () => {} }) }));
+
+import { Composer } from '../src/messaging/Composer';
+import { MessagingProvider } from '../src/messaging/MessagingProvider';
+
+function makeApi() {
+  return {
+    listConversations: vi.fn().mockResolvedValue({ results: [] }), listMessages: vi.fn().mockResolvedValue({ results: [] }), getUnreadCount: vi.fn().mockResolvedValue({ unread_count: 0, by_conversation: {} }),
+    createMessage: vi.fn().mockResolvedValue({ id: 1, conversation_id: 7 }), uploadAttachments: vi.fn().mockResolvedValue({ id: 2, conversation_id: 7 }), getAttachment: vi.fn(), getAttachmentThumbnail: vi.fn(),
+  };
+}
+function renderComposer(api = makeApi(), conversationId = 7) {
+  return render(<MessagingProvider api={api} active={false}><Composer conversationId={conversationId} /></MessagingProvider>);
+}
+function attachmentInput() { return document.querySelector('input[type=file]'); }
+function messageInput() { return screen.getByLabelText('MessagingComposer.MESSAGE'); }
+function imageFile(name = 'photo.png') { return new File(['image'], name, { type: 'image/png' }); }
+
+beforeEach(() => {
+  URL.createObjectURL = vi.fn((file) => `blob:${file.name}`);
+  URL.revokeObjectURL = vi.fn();
+});
+afterEach(() => { cleanup(); vi.restoreAllMocks(); });
+
+describe('Composer chunk 5 behavior', () => {
+  it('sends on Enter and leaves Shift+Enter available for a newline', async () => {
+    const api = makeApi(); renderComposer(api);
+    fireEvent.change(messageInput(), { target: { value: 'first' } });
+    fireEvent.keyDown(messageInput(), { key: 'Enter', code: 'Enter' });
+    await waitFor(() => expect(api.createMessage).toHaveBeenCalledTimes(1));
+
+    fireEvent.change(messageInput(), { target: { value: 'first' } });
+    fireEvent.keyDown(messageInput(), { key: 'Enter', code: 'Enter', shiftKey: true });
+    fireEvent.change(messageInput(), { target: { value: 'first\nsecond' } });
+    expect(api.createMessage).toHaveBeenCalledTimes(1);
+    expect(messageInput().value).toBe('first\nsecond');
+  });
+
+  it('shows staged image previews and removes only the chosen file before upload', async () => {
+    const api = makeApi(); renderComposer(api);
+    const first = imageFile('first.png'); const second = imageFile('second.png');
+    fireEvent.change(attachmentInput(), { target: { files: [first, second] } });
+    expect(screen.getByRole('img', { name: 'first.png' })).toBeTruthy();
+    expect(screen.getByRole('img', { name: 'second.png' })).toBeTruthy();
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingComposer.REMOVE_ATTACHMENT:first.png' }));
+    expect(screen.queryByRole('img', { name: 'first.png' })).toBeNull();
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingComposer.SEND' }));
+    await waitFor(() => expect(api.uploadAttachments).toHaveBeenCalledTimes(1));
+    const sentFiles = Array.from(api.uploadAttachments.mock.calls[0][1].getAll('files[]'));
+    expect(sentFiles).toHaveLength(1);
+    expect(sentFiles[0].name).toBe('second.png');
+  });
+
+  it('shows real byte-percentage upload progress while an attachment upload is in flight', async () => {
+    let resolveUpload; const api = makeApi(); api.uploadAttachments.mockReturnValue(new Promise((resolve) => { resolveUpload = resolve; }));
+    renderComposer(api); fireEvent.change(attachmentInput(), { target: { files: [imageFile()] } });
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingComposer.SEND' }));
+    expect(await screen.findByRole('status')).toBeTruthy();
+    const { onUploadProgress } = api.uploadAttachments.mock.calls[0][2];
+    onUploadProgress({ loaded: 25, total: 100 });
+    await waitFor(() => expect(screen.getAllByRole('progressbar')[0].getAttribute('aria-valuenow')).toBe('25'));
+    resolveUpload({ id: 2, conversation_id: 7 });
+    await waitFor(() => expect(screen.queryByRole('status')).toBeNull());
+  });
+
+  it('compresses oversized images before adding them to FormData and falls back silently if compression fails', async () => {
+    const largeImage = new File([new Uint8Array(2 * 1024 * 1024 + 1)], 'large.png', { type: 'image/png' });
+    const api = makeApi();
+    class SuccessfulImage { naturalWidth = 5120; naturalHeight = 2560; set src(_) { this.onload(); } }
+    vi.stubGlobal('Image', SuccessfulImage);
+    vi.spyOn(HTMLCanvasElement.prototype, 'getContext').mockReturnValue({ drawImage: vi.fn() });
+    vi.spyOn(HTMLCanvasElement.prototype, 'toBlob').mockImplementation((callback) => callback(new Blob(['compressed'], { type: 'image/jpeg' })));
+    renderComposer(api); fireEvent.change(attachmentInput(), { target: { files: [largeImage] } }); fireEvent.click(screen.getByRole('button', { name: 'MessagingComposer.SEND' }));
+    await waitFor(() => expect(api.uploadAttachments).toHaveBeenCalledTimes(1));
+    const compressed = api.uploadAttachments.mock.calls[0][1].get('files[]');
+    expect(compressed.name).toBe('large.jpg'); expect(compressed.type).toBe('image/jpeg');
+
+    cleanup(); const fallbackApi = makeApi(); class FailingImage { set src(_) { this.onerror(); } }
+    vi.stubGlobal('Image', FailingImage);
+    renderComposer(fallbackApi); fireEvent.change(attachmentInput(), { target: { files: [largeImage] } }); fireEvent.click(screen.getByRole('button', { name: 'MessagingComposer.SEND' }));
+    await waitFor(() => expect(fallbackApi.uploadAttachments).toHaveBeenCalledTimes(1));
+    const fallback = fallbackApi.uploadAttachments.mock.calls[0][1].get('files[]');
+    expect(fallback.name).toBe('large.png'); expect(fallback.type).toBe('image/png');
+  });
+
+  it('inserts the selected emoji at the current cursor position', async () => {
+    renderComposer(); fireEvent.change(messageInput(), { target: { value: 'abCD' } });
+    messageInput().setSelectionRange(2, 2);
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingComposer.ADD_EMOJI' }));
+    fireEvent.click(await screen.findByRole('menuitem', { name: '👍' }));
+    await waitFor(() => expect(messageInput().value).toBe('ab👍CD'));
+  });
+
+  it('disables poll composing while an image is staged and resets drafts for a new conversation', async () => {
+    const api = makeApi(); const view = renderComposer(api, 7);
+    fireEvent.change(attachmentInput(), { target: { files: [imageFile()] } });
+    expect(screen.getByRole('button', { name: 'MessagingPoll.CREATE' }).disabled).toBe(true);
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingComposer.REMOVE_ATTACHMENT:photo.png' }));
+    expect(screen.getByRole('button', { name: 'MessagingPoll.CREATE' }).disabled).toBe(false);
+    fireEvent.change(messageInput(), { target: { value: 'unsent draft' } });
+    view.rerender(<MessagingProvider api={api} active={false}><Composer conversationId={8} /></MessagingProvider>);
+    await waitFor(() => expect(messageInput().value).toBe(''));
+  });
+});

package/tests/messagingContractConformance.test.js

@@ -0,0 +1,42 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const root = path.resolve(import.meta.dirname, '..');
+const messagingRoot = path.join(root, 'src', 'messaging');
+
+// These are deliberately named and time-bounded. Chunks 3 and 4 must remove
+// their entries when they wire their existing adapters; the final three are
+// retained only if their stated product rationale still holds at WO close.
+const API_EXEMPTIONS = {
+  createManagedConversation: 'No managed-conversation launcher is in the current public surface.',
+  createObjectThreadConversation: 'Object-thread creation is host-owned routing/scope work.',
+  getMessage: 'Timeline data is loaded through listMessages and listThread.',
+};
+const FRAME_TYPES = ['conversation_upsert', 'conversation_archived', 'message', 'message_edited', 'message_deleted', 'attachment_ready', 'reaction', 'poll_updated', 'delivered', 'read_state', 'thread_read_state', 'participant_changed'];
+const FRAME_EXEMPTIONS = {
+  attachment_ready: 'Reserved by the design and deliberately unemitted.',
+  delivered: 'Receipt synchronisation is outside MSG-3b.',
+  read_state: 'Receipt synchronisation is outside MSG-3b.',
+  thread_read_state: 'Receipt synchronisation is outside MSG-3b.',
+};
+
+describe('messaging adapter and realtime contract conformance', () => {
+  it('has a caller for every API export unless it has an explicit rationale', () => {
+    const apiSource = fs.readFileSync(path.join(messagingRoot, 'api.js'), 'utf8');
+    const source = fs.readdirSync(messagingRoot).filter((file) => file.endsWith('.jsx')).map((file) => fs.readFileSync(path.join(messagingRoot, file), 'utf8')).join('\n');
+    const exports = [...apiSource.matchAll(/export function (\w+)\(/g)].map((match) => match[1]);
+    // Attachment readers are intentionally passed through the provider to the
+    // standalone AttachmentList, where they are called. All other adapters
+    // are invoked by the provider/component that owns the action.
+    const unwired = exports.filter((name) => !new RegExp(`api\\.${name}\\(|${name}: api\\.${name}`).test(source) && !API_EXEMPTIONS[name]);
+    expect(unwired).toEqual([]);
+  });
+
+  it('handles only design-listed frames and accounts for intentionally unhandled frames', () => {
+    const provider = fs.readFileSync(path.join(messagingRoot, 'MessagingProvider.jsx'), 'utf8');
+    const handled = [...provider.matchAll(/frame\.type === '([^']+)'/g)].map((match) => match[1]);
+    expect(handled.every((type) => FRAME_TYPES.includes(type))).toBe(true);
+    expect(FRAME_TYPES.filter((type) => !handled.includes(type) && !FRAME_EXEMPTIONS[type])).toEqual([]);
+  });
+});

package/tests/messagingDirectMessageLauncher.test.jsx

@@ -0,0 +1,78 @@
+// @vitest-environment jsdom
+import React from 'react';
+import { afterEach, 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 { DirectMessageLauncher } from '../src/index';
+import { MessagingProvider } from '../src/messaging/MessagingProvider';
+
+const candidates = [{ id: 2, display_name: 'Alex' }, { id: 3, display_name: 'Sam' }];
+
+function renderLauncher({ api = { createDirectConversation: vi.fn().mockResolvedValue({ id: 41, kind: 'direct' }) }, ...props } = {}) {
+  const onOpen = props.onOpen || vi.fn();
+  render(<MessagingProvider api={api} active={false}><DirectMessageLauncher candidates={candidates} onOpen={onOpen} {...props} /></MessagingProvider>);
+  return { api, onOpen };
+}
+function openPicker() { fireEvent.click(screen.getByRole('button', { name: 'MessagingDirect.LAUNCH' })); }
+
+afterEach(() => {
+  cleanup();
+  window.matchMedia = undefined;
+});
+
+describe('DirectMessageLauncher', () => {
+  it('opens a picker over host-supplied candidates and renders a distinct empty state', () => {
+    renderLauncher();
+    openPicker();
+    expect(screen.getByRole('dialog')).toBeTruthy();
+    expect(screen.getByText('Alex')).toBeTruthy();
+    expect(screen.getByText('Sam')).toBeTruthy();
+
+    cleanup();
+    renderLauncher({ candidates: [] });
+    openPicker();
+    expect(screen.getByText('MessagingDirect.EMPTY')).toBeTruthy();
+  });
+
+  it('requires a recipient, disables while starting, then opens the created conversation with scope', async () => {
+    let resolveRequest;
+    const api = { createDirectConversation: vi.fn(() => new Promise((resolve) => { resolveRequest = resolve; })) };
+    const { onOpen } = renderLauncher({ api, scope: { kind: 'event', id: 8 } });
+    openPicker();
+    const start = screen.getByRole('button', { name: 'MessagingDirect.START' });
+    expect(start.disabled).toBe(true);
+    fireEvent.click(screen.getByText('Alex'));
+    expect(start.disabled).toBe(false);
+    fireEvent.click(start);
+    expect(api.createDirectConversation).toHaveBeenCalledWith({ target_user_id: 2, scope: { kind: 'event', id: 8 } });
+    expect(start.disabled).toBe(true);
+    expect(screen.getByRole('status')).toBeTruthy();
+    resolveRequest({ id: 41, kind: 'direct' });
+    await waitFor(() => expect(onOpen).toHaveBeenCalledWith({ id: 41, kind: 'direct' }));
+    await waitFor(() => expect(screen.queryByRole('dialog')).toBeNull());
+  });
+
+  it('surfaces a policy rejection without closing the picker', async () => {
+    const api = { createDirectConversation: vi.fn().mockRejectedValue({ response: { data: { detail: 'Direct messages are restricted.' } } }) };
+    renderLauncher({ api });
+    openPicker();
+    fireEvent.click(screen.getByText('Alex'));
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingDirect.START' }));
+    expect((await screen.findByRole('alert')).textContent).toContain('Direct messages are restricted.');
+    expect(screen.getByRole('dialog')).toBeTruthy();
+  });
+
+  it('uses a fullscreen dialog at the small-viewport media query', () => {
+    window.matchMedia = vi.fn().mockImplementation(() => ({
+      matches: true,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+    }));
+    renderLauncher();
+    openPicker();
+    expect(document.querySelector('.MuiDialog-paperFullScreen')).not.toBeNull();
+  });
+});

package/tests/messagingExports.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { AttachmentList, Composer, ConversationLaunchers, ConversationList, MessageBubble, MessagingProvider, MessagingScopeConfig, messagingTranslations, PollCard, ReactionBar, ReadTicks, Thread, useMessaging } from '../src/index';
+import { AttachmentList, Composer, ConversationLaunchers, ConversationList, DirectMessageLauncher, MessageBubble, MessagingProvider, MessagingScopeConfig, messagingTranslations, PollCard, ReactionBar, ReadTicks, Thread, useMessaging } from '../src/index';
 
 describe('messaging barrel exports', () => {
   it('exports the provider, hook, standalone list and launchers', () => {
@@ -7,6 +7,7 @@ describe('messaging barrel exports', () => {
     expect(useMessaging).toBeDefined();
     expect(ConversationList).toBeDefined();
     expect(ConversationLaunchers).toBeDefined();
+    expect(DirectMessageLauncher).toBeDefined();
     expect(Thread).toBeDefined();
     expect(MessageBubble).toBeDefined();
     expect(ReadTicks).toBeDefined();

package/tests/messagingMessageActions.test.jsx

@@ -0,0 +1,93 @@
+// @vitest-environment jsdom
+import React from 'react';
+import { afterEach, 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?.message ? `${key}:${options.message}` : key }) }));
+vi.mock('../src/notifications/realtime', () => ({ useRealtime: () => ({ subscribe: () => () => {}, onReconnect: () => () => {} }) }));
+
+import { AuthContext } from '../src/auth/AuthContext';
+import { Composer } from '../src/messaging/Composer';
+import { MessageBubble } from '../src/messaging/MessageBubble';
+import { MessagingProvider } from '../src/messaging/MessagingProvider';
+
+function makeApi() {
+  return {
+    patchMessage: vi.fn().mockImplementation(async (id, patch) => ({ id, ...patch, edited_at: '2026-07-31T10:01:00Z' })),
+    deleteMessage: vi.fn().mockImplementation(async (id) => ({ id, deleted_at: '2026-07-31T10:01:00Z' })),
+  };
+}
+function renderBubble(message, { userId = 1, canModerateMessages = false, api = makeApi() } = {}) {
+  const result = render(<AuthContext.Provider value={{ user: { id: userId } }}><MessagingProvider api={api} active={false}><MessageBubble message={message} canModerateMessages={canModerateMessages} /></MessagingProvider></AuthContext.Provider>);
+  return { ...result, api };
+}
+function openActions() { fireEvent.click(screen.getByRole('button', { name: 'MessagingActions.MENU' })); }
+
+afterEach(cleanup);
+
+describe('message actions', () => {
+  it('gates the menu to the author or host-supplied moderator capability, never deleted or poll messages', () => {
+    const mine = { id: 1, body: 'Mine', sender: { id: 1 } };
+    const theirs = { id: 2, body: 'Theirs', sender: { id: 2 } };
+    const { rerender } = renderBubble(mine);
+    expect(screen.getByRole('button', { name: 'MessagingActions.MENU' })).toBeTruthy();
+    rerender(<AuthContext.Provider value={{ user: { id: 1 } }}><MessagingProvider api={makeApi()} active={false}><MessageBubble message={theirs} /></MessagingProvider></AuthContext.Provider>);
+    expect(screen.queryByRole('button', { name: 'MessagingActions.MENU' })).toBeNull();
+    rerender(<AuthContext.Provider value={{ user: { id: 1 } }}><MessagingProvider api={makeApi()} active={false}><MessageBubble message={theirs} canModerateMessages /></MessagingProvider></AuthContext.Provider>);
+    expect(screen.getByRole('button', { name: 'MessagingActions.MENU' })).toBeTruthy();
+    rerender(<AuthContext.Provider value={{ user: { id: 1 } }}><MessagingProvider api={makeApi()} active={false}><MessageBubble message={{ ...mine, deleted_at: '2026-07-31T10:00:00Z' }} /></MessagingProvider></AuthContext.Provider>);
+    expect(screen.queryByRole('button', { name: 'MessagingActions.MENU' })).toBeNull();
+    rerender(<AuthContext.Provider value={{ user: { id: 1 } }}><MessagingProvider api={makeApi()} active={false}><MessageBubble message={{ ...mine, kind: 'poll' }} /></MessagingProvider></AuthContext.Provider>);
+    expect(screen.queryByRole('button', { name: 'MessagingActions.MENU' })).toBeNull();
+  });
+
+  it('edits an author message through the API and auto-cancels when deleted elsewhere', async () => {
+    const api = makeApi();
+    const message = { id: 4, body: 'Before', sender: { id: 1 } };
+    const { rerender } = renderBubble(message, { api });
+    openActions();
+    fireEvent.click(screen.getByRole('menuitem', { name: 'MessagingActions.EDIT' }));
+    const field = screen.getByRole('textbox', { name: 'MessagingActions.EDIT' });
+    fireEvent.change(field, { target: { value: 'After' } });
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingActions.SAVE' }));
+    await waitFor(() => expect(api.patchMessage).toHaveBeenCalledWith(4, { body: 'After' }));
+    openActions();
+    fireEvent.click(screen.getByRole('menuitem', { name: 'MessagingActions.EDIT' }));
+    expect(screen.getByRole('textbox', { name: 'MessagingActions.EDIT' })).toBeTruthy();
+    rerender(<AuthContext.Provider value={{ user: { id: 1 } }}><MessagingProvider api={api} active={false}><MessageBubble message={{ ...message, deleted_at: '2026-07-31T10:02:00Z' }} /></MessagingProvider></AuthContext.Provider>);
+    await waitFor(() => expect(screen.queryByRole('textbox', { name: 'MessagingActions.EDIT' })).toBeNull());
+  });
+
+  it('requires confirmation before author or moderator deletion reaches the API', async () => {
+    const api = makeApi();
+    const { rerender } = renderBubble({ id: 5, body: 'Delete me', sender: { id: 1 } }, { api });
+    openActions();
+    fireEvent.click(screen.getByRole('menuitem', { name: 'MessagingActions.DELETE' }));
+    expect(api.deleteMessage).not.toHaveBeenCalled();
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingActions.DELETE' }));
+    await waitFor(() => expect(api.deleteMessage).toHaveBeenCalledWith(5));
+    await waitFor(() => expect(screen.queryByRole('dialog')).toBeNull());
+    const moderatorApi = makeApi();
+    rerender(<AuthContext.Provider value={{ user: { id: 1 } }}><MessagingProvider api={moderatorApi} active={false}><MessageBubble message={{ id: 6, body: 'Moderator delete', sender: { id: 2 } }} canModerateMessages /></MessagingProvider></AuthContext.Provider>);
+    openActions();
+    fireEvent.click(screen.getByRole('menuitem', { name: 'MessagingActions.DELETE' }));
+    fireEvent.click(screen.getByRole('button', { name: 'MessagingActions.DELETE' }));
+    await waitFor(() => expect(moderatorApi.deleteMessage).toHaveBeenCalledWith(6));
+  });
+
+  it('clears a deleted reply target and copies the exact message body', async () => {
+    const onReplyTargetChange = vi.fn();
+    const replyTarget = { id: 7, body: 'Reply source', sender: { display_name: 'Ava' } };
+    const { rerender } = render(<MessagingProvider api={makeApi()} active={false}><Composer conversationId={1} replyTarget={replyTarget} onReplyTargetChange={onReplyTargetChange} /></MessagingProvider>);
+    onReplyTargetChange.mockClear();
+    rerender(<MessagingProvider api={makeApi()} active={false}><Composer conversationId={1} replyTarget={{ ...replyTarget, deleted_at: '2026-07-31T10:00:00Z' }} onReplyTargetChange={onReplyTargetChange} /></MessagingProvider>);
+    await waitFor(() => expect(onReplyTargetChange).toHaveBeenCalledWith(null));
+
+    const writeText = vi.fn().mockResolvedValue(undefined);
+    Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText } });
+    renderBubble({ id: 8, body: 'Copy exactly this', sender: { id: 1 } });
+    openActions();
+    fireEvent.click(screen.getByRole('menuitem', { name: 'MessagingActions.COPY' }));
+    await waitFor(() => expect(writeText).toHaveBeenCalledWith('Copy exactly this'));
+  });
+});