From 45e8fb62a10b500ce45d468da6655a3ea5075631 Mon Sep 17 00:00:00 2001
From: Oliver Lazoroski <oliver.lazoroski@gmail.com>
Date: Thu, 29 Oct 2026 11:59:13 +0100
Subject: [PATCH 1/5] fix(Message): show error notification when pinning or
 unpinning fails

---
 .../hooks/__tests__/usePinHandler.test.tsx    | 122 ++++++++++++++++++
 src/components/Message/hooks/usePinHandler.ts |   2 +
 2 files changed, 124 insertions(+)
 create mode 100644 src/components/Message/hooks/__tests__/usePinHandler.test.tsx

diff --git a/src/components/Message/hooks/__tests__/usePinHandler.test.tsx b/src/components/Message/hooks/__tests__/usePinHandler.test.tsx
new file mode 100644
index 0000000000..48bebf4ce9
--- /dev/null
+++ b/src/components/Message/hooks/__tests__/usePinHandler.test.tsx
@@ -0,0 +1,122 @@
+import React from 'react';
+import { act, renderHook, type RenderHookResult } from '@testing-library/react';
+import { fromPartial } from '@total-typescript/shoehorn';
+import type { Channel as ChannelType, LocalMessage, StreamChat } from 'stream-chat';
+
+import { usePinHandler } from '../usePinHandler';
+import {
+  generateChannel,
+  generateMessage,
+  generateUser,
+  getOrCreateChannelApi,
+  getTestClientWithUser,
+  useMockedApis,
+} from '../../../../mock-builders';
+import { Channel } from '../../../Channel';
+import { Chat } from '../../../Chat';
+
+// `usePinHandler` updates the message optimistically through `messagePaginator.ingestItem`,
+// rolls it back when the request fails, and rethrows so callers (the Pin message action) can
+// show an error notification instead of a success one.
+
+let channel: ChannelType;
+let client: StreamChat;
+const mouseEventMock = fromPartial<React.BaseSyntheticEvent>({
+  preventDefault: vi.fn(() => {}),
+});
+
+async function renderUsePinHandler(
+  message: LocalMessage,
+  notifications?: Parameters<typeof usePinHandler>[1],
+) {
+  const wrapper = ({ children }: React.PropsWithChildren) => (
+    <Chat client={client}>
+      <Channel channel={channel}>{children}</Channel>
+    </Chat>
+  );
+  let rendered: RenderHookResult<ReturnType<typeof usePinHandler>, unknown>;
+  await act(async () => {
+    rendered = await renderHook(() => usePinHandler(message, notifications), {
+      wrapper,
+    });
+  });
+
+  return rendered!.result.current;
+}
+
+describe('usePinHandler custom hook', () => {
+  beforeAll(async () => {
+    client = await getTestClientWithUser(generateUser());
+    const channelData = generateChannel();
+    useMockedApis(client, [getOrCreateChannelApi(channelData)]);
+    channel = client.channel('messaging', channelData.channel.id);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('should pin the message and update it optimistically', async () => {
+    const pinSpy = vi.spyOn(client, 'pinMessage').mockResolvedValue(fromPartial({}));
+    const ingestSpy = vi.spyOn(channel.messagePaginator, 'ingestItem');
+    const message = generateMessage({ pinned: false }) as LocalMessage;
+    const { handlePin } = await renderUsePinHandler(message);
+    await act(async () => {
+      await handlePin(mouseEventMock);
+    });
+    expect(pinSpy).toHaveBeenCalledWith(message);
+    expect(ingestSpy).toHaveBeenCalledTimes(1);
+    expect(ingestSpy).toHaveBeenCalledWith(expect.objectContaining({ pinned: true }));
+  });
+
+  it('should roll back and throw when pinning fails', async () => {
+    vi.spyOn(client, 'pinMessage').mockRejectedValue(new Error('pin failed'));
+    const ingestSpy = vi.spyOn(channel.messagePaginator, 'ingestItem');
+    const message = generateMessage({ pinned: false }) as LocalMessage;
+    const { handlePin } = await renderUsePinHandler(message);
+    await act(async () => {
+      await expect(handlePin(mouseEventMock)).rejects.toThrow('pin failed');
+    });
+    expect(ingestSpy).toHaveBeenCalledTimes(2);
+    expect(ingestSpy).toHaveBeenLastCalledWith(message);
+  });
+
+  it('should unpin the message and update it optimistically', async () => {
+    const unpinSpy = vi.spyOn(client, 'unpinMessage').mockResolvedValue(fromPartial({}));
+    const ingestSpy = vi.spyOn(channel.messagePaginator, 'ingestItem');
+    const message = generateMessage({ pinned: true }) as LocalMessage;
+    const { handlePin } = await renderUsePinHandler(message);
+    await act(async () => {
+      await handlePin(mouseEventMock);
+    });
+    expect(unpinSpy).toHaveBeenCalledWith(message);
+    expect(ingestSpy).toHaveBeenCalledTimes(1);
+    expect(ingestSpy).toHaveBeenCalledWith(expect.objectContaining({ pinned: false }));
+  });
+
+  it('should roll back and throw when unpinning fails', async () => {
+    vi.spyOn(client, 'unpinMessage').mockRejectedValue(new Error('unpin failed'));
+    const ingestSpy = vi.spyOn(channel.messagePaginator, 'ingestItem');
+    const message = generateMessage({ pinned: true }) as LocalMessage;
+    const { handlePin } = await renderUsePinHandler(message);
+    await act(async () => {
+      await expect(handlePin(mouseEventMock)).rejects.toThrow('unpin failed');
+    });
+    expect(ingestSpy).toHaveBeenCalledTimes(2);
+    expect(ingestSpy).toHaveBeenLastCalledWith(message);
+  });
+
+  it('should notify and throw when pinning fails with notifications configured', async () => {
+    vi.spyOn(client, 'pinMessage').mockRejectedValue(new Error('pin failed'));
+    const notify = vi.fn();
+    const message = generateMessage({ pinned: false }) as LocalMessage;
+    const { handlePin } = await renderUsePinHandler(message, {
+      getErrorNotification: () => 'custom pin error',
+      notify,
+    });
+    await act(async () => {
+      await expect(handlePin(mouseEventMock)).rejects.toThrow('pin failed');
+    });
+    expect(notify).toHaveBeenCalledWith('custom pin error', 'error');
+  });
+});
diff --git a/src/components/Message/hooks/usePinHandler.ts b/src/components/Message/hooks/usePinHandler.ts
index ff8bce29e7..f56d417dbd 100644
--- a/src/components/Message/hooks/usePinHandler.ts
+++ b/src/components/Message/hooks/usePinHandler.ts
@@ -78,6 +78,7 @@ export const usePinHandler = (
             'error',
           );
         messagePaginator.ingestItem(message);
+        throw e;
       }
     } else {
       try {
@@ -103,6 +104,7 @@ export const usePinHandler = (
             'error',
           );
         messagePaginator.ingestItem(message);
+        throw e;
       }
     }
   };

From 72e7798825c5ef357c615a60ec36bf4397a265c1 Mon Sep 17 00:00:00 2001
From: Oliver Lazoroski <oliver.lazoroski@gmail.com>
Date: Thu, 29 Oct 2026 12:10:21 +0100
Subject: [PATCH 2/5] test(Message): assert paginator state in usePinHandler
 tests

---
 .../hooks/__tests__/usePinHandler.test.tsx    | 67 +++++++++++++------
 1 file changed, 46 insertions(+), 21 deletions(-)

diff --git a/src/components/Message/hooks/__tests__/usePinHandler.test.tsx b/src/components/Message/hooks/__tests__/usePinHandler.test.tsx
index 48bebf4ce9..f31a21620f 100644
--- a/src/components/Message/hooks/__tests__/usePinHandler.test.tsx
+++ b/src/components/Message/hooks/__tests__/usePinHandler.test.tsx
@@ -25,6 +25,11 @@ const mouseEventMock = fromPartial<React.BaseSyntheticEvent>({
   preventDefault: vi.fn(() => {}),
 });
 
+// Reads the message back from the channel's paginator, so assertions see the stored state
+// rather than only the calls made to it.
+const getHeldMessage = (id: string) =>
+  channel.messagePaginator.items?.find((item) => item.id === id);
+
 async function renderUsePinHandler(
   message: LocalMessage,
   notifications?: Parameters<typeof usePinHandler>[1],
@@ -58,58 +63,78 @@ describe('usePinHandler custom hook', () => {
 
   it('should pin the message and update it optimistically', async () => {
     const pinSpy = vi.spyOn(client, 'pinMessage').mockResolvedValue(fromPartial({}));
-    const ingestSpy = vi.spyOn(channel.messagePaginator, 'ingestItem');
-    const message = generateMessage({ pinned: false }) as LocalMessage;
+    const message = generateMessage({ cid: channel.cid, pinned: false }) as LocalMessage;
     const { handlePin } = await renderUsePinHandler(message);
     await act(async () => {
       await handlePin(mouseEventMock);
     });
     expect(pinSpy).toHaveBeenCalledWith(message);
-    expect(ingestSpy).toHaveBeenCalledTimes(1);
-    expect(ingestSpy).toHaveBeenCalledWith(expect.objectContaining({ pinned: true }));
+    expect(getHeldMessage(message.id)).toEqual(expect.objectContaining({ pinned: true }));
   });
 
   it('should roll back and throw when pinning fails', async () => {
-    vi.spyOn(client, 'pinMessage').mockRejectedValue(new Error('pin failed'));
-    const ingestSpy = vi.spyOn(channel.messagePaginator, 'ingestItem');
-    const message = generateMessage({ pinned: false }) as LocalMessage;
+    let rejectRequest: (error: Error) => void = () => {};
+    vi.spyOn(client, 'pinMessage').mockReturnValue(
+      new Promise((_, reject) => {
+        rejectRequest = reject;
+      }),
+    );
+    const message = generateMessage({ cid: channel.cid, pinned: false }) as LocalMessage;
     const { handlePin } = await renderUsePinHandler(message);
+    let pending: ReturnType<typeof handlePin>;
+    act(() => {
+      pending = handlePin(mouseEventMock);
+    });
+    expect(getHeldMessage(message.id)).toEqual(expect.objectContaining({ pinned: true }));
     await act(async () => {
-      await expect(handlePin(mouseEventMock)).rejects.toThrow('pin failed');
+      rejectRequest(new Error('pin failed'));
+      await expect(pending).rejects.toThrow('pin failed');
     });
-    expect(ingestSpy).toHaveBeenCalledTimes(2);
-    expect(ingestSpy).toHaveBeenLastCalledWith(message);
+    expect(getHeldMessage(message.id)).toEqual(
+      expect.objectContaining({ pinned: false }),
+    );
   });
 
   it('should unpin the message and update it optimistically', async () => {
     const unpinSpy = vi.spyOn(client, 'unpinMessage').mockResolvedValue(fromPartial({}));
-    const ingestSpy = vi.spyOn(channel.messagePaginator, 'ingestItem');
-    const message = generateMessage({ pinned: true }) as LocalMessage;
+    const message = generateMessage({ cid: channel.cid, pinned: true }) as LocalMessage;
     const { handlePin } = await renderUsePinHandler(message);
     await act(async () => {
       await handlePin(mouseEventMock);
     });
     expect(unpinSpy).toHaveBeenCalledWith(message);
-    expect(ingestSpy).toHaveBeenCalledTimes(1);
-    expect(ingestSpy).toHaveBeenCalledWith(expect.objectContaining({ pinned: false }));
+    expect(getHeldMessage(message.id)).toEqual(
+      expect.objectContaining({ pinned: false }),
+    );
   });
 
   it('should roll back and throw when unpinning fails', async () => {
-    vi.spyOn(client, 'unpinMessage').mockRejectedValue(new Error('unpin failed'));
-    const ingestSpy = vi.spyOn(channel.messagePaginator, 'ingestItem');
-    const message = generateMessage({ pinned: true }) as LocalMessage;
+    let rejectRequest: (error: Error) => void = () => {};
+    vi.spyOn(client, 'unpinMessage').mockReturnValue(
+      new Promise((_, reject) => {
+        rejectRequest = reject;
+      }),
+    );
+    const message = generateMessage({ cid: channel.cid, pinned: true }) as LocalMessage;
     const { handlePin } = await renderUsePinHandler(message);
+    let pending: ReturnType<typeof handlePin>;
+    act(() => {
+      pending = handlePin(mouseEventMock);
+    });
+    expect(getHeldMessage(message.id)).toEqual(
+      expect.objectContaining({ pinned: false }),
+    );
     await act(async () => {
-      await expect(handlePin(mouseEventMock)).rejects.toThrow('unpin failed');
+      rejectRequest(new Error('unpin failed'));
+      await expect(pending).rejects.toThrow('unpin failed');
     });
-    expect(ingestSpy).toHaveBeenCalledTimes(2);
-    expect(ingestSpy).toHaveBeenLastCalledWith(message);
+    expect(getHeldMessage(message.id)).toEqual(expect.objectContaining({ pinned: true }));
   });
 
   it('should notify and throw when pinning fails with notifications configured', async () => {
     vi.spyOn(client, 'pinMessage').mockRejectedValue(new Error('pin failed'));
     const notify = vi.fn();
-    const message = generateMessage({ pinned: false }) as LocalMessage;
+    const message = generateMessage({ cid: channel.cid, pinned: false }) as LocalMessage;
     const { handlePin } = await renderUsePinHandler(message, {
       getErrorNotification: () => 'custom pin error',
       notify,

From dd0f13f632296260d006d327447c99b17b1cd14d Mon Sep 17 00:00:00 2001
From: Oliver Lazoroski <oliver.lazoroski@gmail.com>
Date: Thu, 29 Oct 2026 12:19:59 +0100
Subject: [PATCH 3/5] fix(Message): keep concurrent updates when rolling back a
 failed pin

---
 .../vite/src/CustomMessageUi/variants.tsx     |  11 +-
 .../hooks/__tests__/usePinHandler.test.tsx    | 166 ++++++++++++------
 src/components/Message/hooks/usePinHandler.ts |  57 ++++--
 src/context/MessageContext.tsx                |   1 +
 4 files changed, 160 insertions(+), 75 deletions(-)

diff --git a/examples/vite/src/CustomMessageUi/variants.tsx b/examples/vite/src/CustomMessageUi/variants.tsx
index 64b9bbf898..bfc01324d6 100644
--- a/examples/vite/src/CustomMessageUi/variants.tsx
+++ b/examples/vite/src/CustomMessageUi/variants.tsx
@@ -247,7 +247,16 @@ const CustomMessageUiActions = () => {
   return (
     <div className='custom-message-ui__actions'>
       <div className='custom-message-ui__actions-group'>
-        <button onClick={handlePin} title={message.pinned ? 'Unpin' : 'Pin'}>
+        <button
+          onClick={async (event) => {
+            try {
+              await handlePin(event);
+            } catch (error) {
+              console.error('Failed to update the message pin', error);
+            }
+          }}
+          title={message.pinned ? 'Unpin' : 'Pin'}
+        >
           {message.pinned ? '📍' : '📌'}
         </button>
         <button onClick={() => handleDelete()} title='Delete'>
diff --git a/src/components/Message/hooks/__tests__/usePinHandler.test.tsx b/src/components/Message/hooks/__tests__/usePinHandler.test.tsx
index f31a21620f..5d33e66a12 100644
--- a/src/components/Message/hooks/__tests__/usePinHandler.test.tsx
+++ b/src/components/Message/hooks/__tests__/usePinHandler.test.tsx
@@ -16,8 +16,8 @@ import { Channel } from '../../../Channel';
 import { Chat } from '../../../Chat';
 
 // `usePinHandler` updates the message optimistically through `messagePaginator.ingestItem`,
-// rolls it back when the request fails, and rethrows so callers (the Pin message action) can
-// show an error notification instead of a success one.
+// rolls back only the pin fields when the request fails, and rethrows so callers (the Pin
+// message action) can show an error notification instead of a success one.
 
 let channel: ChannelType;
 let client: StreamChat;
@@ -25,11 +25,6 @@ const mouseEventMock = fromPartial<React.BaseSyntheticEvent>({
   preventDefault: vi.fn(() => {}),
 });
 
-// Reads the message back from the channel's paginator, so assertions see the stored state
-// rather than only the calls made to it.
-const getHeldMessage = (id: string) =>
-  channel.messagePaginator.items?.find((item) => item.id === id);
-
 async function renderUsePinHandler(
   message: LocalMessage,
   notifications?: Parameters<typeof usePinHandler>[1],
@@ -49,6 +44,28 @@ async function renderUsePinHandler(
   return rendered!.result.current;
 }
 
+// Keeps the pin/unpin request pending; the returned function rejects it.
+const mockPendingRequest = (method: 'pinMessage' | 'unpinMessage') => {
+  let rejectRequest: (error: Error) => void = () => {};
+  vi.spyOn(client, method).mockReturnValue(
+    new Promise((_, reject) => {
+      rejectRequest = reject;
+    }),
+  );
+  return rejectRequest;
+};
+
+// Starts `handlePin` without awaiting it, so assertions can run while the request is pending.
+const startHandlePin = (handlePin: ReturnType<typeof usePinHandler>['handlePin']) => {
+  let pending: ReturnType<typeof handlePin> = undefined;
+  act(() => {
+    pending = handlePin(mouseEventMock);
+  });
+  return pending;
+};
+
+const getStoredMessage = (id: string) => channel.messagePaginator.getItem(id);
+
 describe('usePinHandler custom hook', () => {
   beforeAll(async () => {
     client = await getTestClientWithUser(generateUser());
@@ -61,74 +78,93 @@ describe('usePinHandler custom hook', () => {
     vi.restoreAllMocks();
   });
 
-  it('should pin the message and update it optimistically', async () => {
-    const pinSpy = vi.spyOn(client, 'pinMessage').mockResolvedValue(fromPartial({}));
-    const message = generateMessage({ cid: channel.cid, pinned: false }) as LocalMessage;
-    const { handlePin } = await renderUsePinHandler(message);
-    await act(async () => {
-      await handlePin(mouseEventMock);
-    });
-    expect(pinSpy).toHaveBeenCalledWith(message);
-    expect(getHeldMessage(message.id)).toEqual(expect.objectContaining({ pinned: true }));
-  });
+  it.each([
+    { method: 'pinMessage', pinned: false },
+    { method: 'unpinMessage', pinned: true },
+  ] as const)(
+    'should update the message optimistically when $method succeeds',
+    async ({ method, pinned }) => {
+      const requestSpy = vi.spyOn(client, method).mockResolvedValue(fromPartial({}));
+      const message = generateMessage({ cid: channel.cid, pinned }) as LocalMessage;
+      const { handlePin } = await renderUsePinHandler(message);
+      await act(async () => {
+        await handlePin(mouseEventMock);
+      });
+      expect(requestSpy).toHaveBeenCalledWith(message);
+      expect(getStoredMessage(message.id)).toEqual(
+        expect.objectContaining({ pinned: !pinned }),
+      );
+    },
+  );
 
-  it('should roll back and throw when pinning fails', async () => {
-    let rejectRequest: (error: Error) => void = () => {};
-    vi.spyOn(client, 'pinMessage').mockReturnValue(
-      new Promise((_, reject) => {
-        rejectRequest = reject;
-      }),
-    );
-    const message = generateMessage({ cid: channel.cid, pinned: false }) as LocalMessage;
+  it.each([
+    { method: 'pinMessage', pinned: false },
+    { method: 'unpinMessage', pinned: true },
+  ] as const)(
+    'should roll back and throw when $method fails',
+    async ({ method, pinned }) => {
+      const rejectRequest = mockPendingRequest(method);
+      const message = generateMessage({ cid: channel.cid, pinned }) as LocalMessage;
+      const { handlePin } = await renderUsePinHandler(message);
+      const pending = startHandlePin(handlePin);
+      expect(getStoredMessage(message.id)).toEqual(
+        expect.objectContaining({ pinned: !pinned }),
+      );
+      await act(async () => {
+        rejectRequest(new Error('request failed'));
+        await expect(pending).rejects.toThrow('request failed');
+      });
+      expect(getStoredMessage(message.id)).toEqual(expect.objectContaining({ pinned }));
+    },
+  );
+
+  it('should keep updates that arrived while the request was pending when rolling back', async () => {
+    const rejectRequest = mockPendingRequest('pinMessage');
+    const message = generateMessage({
+      cid: channel.cid,
+      pinned: false,
+      text: 'original',
+    }) as LocalMessage;
     const { handlePin } = await renderUsePinHandler(message);
-    let pending: ReturnType<typeof handlePin>;
+    const pending = startHandlePin(handlePin);
     act(() => {
-      pending = handlePin(mouseEventMock);
+      channel.messagePaginator.ingestItem({
+        ...getStoredMessage(message.id)!,
+        text: 'edited while pinning',
+      });
     });
-    expect(getHeldMessage(message.id)).toEqual(expect.objectContaining({ pinned: true }));
     await act(async () => {
       rejectRequest(new Error('pin failed'));
       await expect(pending).rejects.toThrow('pin failed');
     });
-    expect(getHeldMessage(message.id)).toEqual(
-      expect.objectContaining({ pinned: false }),
+    expect(getStoredMessage(message.id)).toEqual(
+      expect.objectContaining({ pinned: false, text: 'edited while pinning' }),
     );
   });
 
-  it('should unpin the message and update it optimistically', async () => {
-    const unpinSpy = vi.spyOn(client, 'unpinMessage').mockResolvedValue(fromPartial({}));
-    const message = generateMessage({ cid: channel.cid, pinned: true }) as LocalMessage;
+  it('should keep a pin state that changed while the request was pending', async () => {
+    const rejectRequest = mockPendingRequest('unpinMessage');
+    const originalPinner = generateUser();
+    const newerPinner = generateUser();
+    const message = generateMessage({
+      cid: channel.cid,
+      pinned: true,
+      pinned_by: originalPinner,
+    }) as LocalMessage;
     const { handlePin } = await renderUsePinHandler(message);
-    await act(async () => {
-      await handlePin(mouseEventMock);
-    });
-    expect(unpinSpy).toHaveBeenCalledWith(message);
-    expect(getHeldMessage(message.id)).toEqual(
-      expect.objectContaining({ pinned: false }),
-    );
-  });
-
-  it('should roll back and throw when unpinning fails', async () => {
-    let rejectRequest: (error: Error) => void = () => {};
-    vi.spyOn(client, 'unpinMessage').mockReturnValue(
-      new Promise((_, reject) => {
-        rejectRequest = reject;
-      }),
-    );
-    const message = generateMessage({ cid: channel.cid, pinned: true }) as LocalMessage;
-    const { handlePin } = await renderUsePinHandler(message);
-    let pending: ReturnType<typeof handlePin>;
+    const pending = startHandlePin(handlePin);
     act(() => {
-      pending = handlePin(mouseEventMock);
+      channel.messagePaginator.ingestItem({
+        ...getStoredMessage(message.id)!,
+        pinned: true,
+        pinned_by: newerPinner,
+      });
     });
-    expect(getHeldMessage(message.id)).toEqual(
-      expect.objectContaining({ pinned: false }),
-    );
     await act(async () => {
       rejectRequest(new Error('unpin failed'));
       await expect(pending).rejects.toThrow('unpin failed');
     });
-    expect(getHeldMessage(message.id)).toEqual(expect.objectContaining({ pinned: true }));
+    expect(getStoredMessage(message.id)?.pinned_by).toEqual(newerPinner);
   });
 
   it('should notify and throw when pinning fails with notifications configured', async () => {
@@ -144,4 +180,20 @@ describe('usePinHandler custom hook', () => {
     });
     expect(notify).toHaveBeenCalledWith('custom pin error', 'error');
   });
+
+  it('should roll back even when the notify callback throws', async () => {
+    vi.spyOn(client, 'pinMessage').mockRejectedValue(new Error('pin failed'));
+    const message = generateMessage({ cid: channel.cid, pinned: false }) as LocalMessage;
+    const { handlePin } = await renderUsePinHandler(message, {
+      notify: () => {
+        throw new Error('notify failed');
+      },
+    });
+    await act(async () => {
+      await expect(handlePin(mouseEventMock)).rejects.toThrow('notify failed');
+    });
+    expect(getStoredMessage(message.id)).toEqual(
+      expect.objectContaining({ pinned: false }),
+    );
+  });
 });
diff --git a/src/components/Message/hooks/usePinHandler.ts b/src/components/Message/hooks/usePinHandler.ts
index f56d417dbd..b22bfde932 100644
--- a/src/components/Message/hooks/usePinHandler.ts
+++ b/src/components/Message/hooks/usePinHandler.ts
@@ -50,24 +50,46 @@ export const usePinHandler = (
   const { client } = useChatContext();
   const { t } = useTranslationContext();
 
+  // The stored message, which may be newer than the `message` this hook rendered with.
+  const getLatestMessage = () => messagePaginator.getItem(message.id) ?? message;
+
+  // Restores only the pin fields from before the click, so updates that arrived while the request
+  // was in flight (an edit, a reaction) are kept. Skipped when the pin state already changed
+  // again, since that change is newer than the snapshot.
+  const rollBackPin = (optimisticMessage: LocalMessage) => {
+    const latestMessage = messagePaginator.getItem(message.id);
+    if (!latestMessage || latestMessage.pinned !== optimisticMessage.pinned) return;
+
+    messagePaginator.ingestItem({
+      ...latestMessage,
+      pin_expires: message.pin_expires,
+      pinned: message.pinned,
+      pinned_at: message.pinned_at,
+      pinned_by: message.pinned_by,
+    });
+  };
+
   const handlePin: ReactEventHandler = async (event) => {
     event.preventDefault();
 
     if (!message) return;
 
     if (!message.pinned) {
-      try {
-        const optimisticMessage: LocalMessage = {
-          ...message,
-          pinned: true,
-          pinned_at: nowNs(),
-          pinned_by: client.user as UserResponse | undefined,
-        };
+      const optimisticMessage: LocalMessage = {
+        ...getLatestMessage(),
+        pinned: true,
+        pinned_at: nowNs(),
+        pinned_by: client.user as UserResponse | undefined,
+      };
 
+      try {
         messagePaginator.ingestItem(optimisticMessage);
 
         await client.pinMessage(message);
       } catch (e) {
+        // Roll back first, so a throwing notification callback cannot leave the optimistic state.
+        rollBackPin(optimisticMessage);
+
         const errorMessage =
           getErrorNotification && validateAndGetMessage(getErrorNotification, [message]);
 
@@ -77,23 +99,25 @@ export const usePinHandler = (
               t('common.errorPinningMessage.label', 'Error pinning message'),
             'error',
           );
-        messagePaginator.ingestItem(message);
         throw e;
       }
     } else {
-      try {
-        const optimisticMessage: LocalMessage = {
-          ...message,
-          pin_expires: undefined,
-          pinned: false,
-          pinned_at: undefined,
-          pinned_by: undefined,
-        };
+      const optimisticMessage: LocalMessage = {
+        ...getLatestMessage(),
+        pin_expires: undefined,
+        pinned: false,
+        pinned_at: undefined,
+        pinned_by: undefined,
+      };
 
+      try {
         messagePaginator.ingestItem(optimisticMessage);
 
         await client.unpinMessage(message);
       } catch (e) {
+        // Roll back first, so a throwing notification callback cannot leave the optimistic state.
+        rollBackPin(optimisticMessage);
+
         const errorMessage =
           getErrorNotification && validateAndGetMessage(getErrorNotification, [message]);
 
@@ -103,7 +127,6 @@ export const usePinHandler = (
               t('common.errorRemovingMessagePin.label', 'Error removing message pin'),
             'error',
           );
-        messagePaginator.ingestItem(message);
         throw e;
       }
     }
diff --git a/src/context/MessageContext.tsx b/src/context/MessageContext.tsx
index 4bcd4aa747..d797a8d065 100644
--- a/src/context/MessageContext.tsx
+++ b/src/context/MessageContext.tsx
@@ -32,6 +32,7 @@ export type MessageContextValue = {
   handleMute: ReactEventHandler;
   /** Opens the message's thread: the `openThread` prop of `Message`, else ChatView navigation. */
   handleOpenThread: ReactEventHandler;
+  /** Pins or unpins the message. Rejects with the request's error when it fails, after rolling back. */
   handlePin: ReactEventHandler;
   handleReaction: (
     reactionType: string,

From bafd2efe8741a9989d4452c669e814415809c8fb Mon Sep 17 00:00:00 2001
From: Oliver Lazoroski <oliver.lazoroski@gmail.com>
Date: Thu, 29 Oct 2026 13:53:02 +0100
Subject: [PATCH 4/5] fix(Message): rethrow failed mute and delete requests

---
 .../vite/src/CustomMessageUi/variants.tsx     | 11 +++++-
 .../Message/__tests__/Message.test.tsx        |  4 +-
 .../hooks/__tests__/useDeleteHandler.test.tsx | 14 ++++++-
 .../hooks/__tests__/useMuteHandler.test.tsx   | 39 +++++++++++++++----
 .../Message/hooks/useDeleteHandler.ts         |  1 +
 .../Message/hooks/useMuteHandler.ts           | 32 ++++++++-------
 6 files changed, 74 insertions(+), 27 deletions(-)

diff --git a/examples/vite/src/CustomMessageUi/variants.tsx b/examples/vite/src/CustomMessageUi/variants.tsx
index bfc01324d6..3eb1294546 100644
--- a/examples/vite/src/CustomMessageUi/variants.tsx
+++ b/examples/vite/src/CustomMessageUi/variants.tsx
@@ -259,7 +259,16 @@ const CustomMessageUiActions = () => {
         >
           {message.pinned ? '📍' : '📌'}
         </button>
-        <button onClick={() => handleDelete()} title='Delete'>
+        <button
+          onClick={async () => {
+            try {
+              await handleDelete();
+            } catch (error) {
+              console.error('Failed to delete the message', error);
+            }
+          }}
+          title='Delete'
+        >
           🗑️
         </button>
         <button onClick={handleOpenThread} title='Open thread'>
diff --git a/src/components/Message/__tests__/Message.test.tsx b/src/components/Message/__tests__/Message.test.tsx
index c9f3f0e472..f47f2deb7c 100644
--- a/src/components/Message/__tests__/Message.test.tsx
+++ b/src/components/Message/__tests__/Message.test.tsx
@@ -474,7 +474,7 @@ describe('<Message /> component', () => {
       message,
     });
 
-    await context.handleMute(mouseEventMock);
+    await expect(context.handleMute(mouseEventMock)).rejects.toThrow('mute failed');
 
     expect(muteUser).toHaveBeenCalledWith({ target_ids: [bob.id] });
   });
@@ -521,7 +521,7 @@ describe('<Message /> component', () => {
       message,
     });
 
-    await context.handleMute(mouseEventMock);
+    await expect(context.handleMute(mouseEventMock)).rejects.toThrow('unmute failed');
 
     expect(unmuteUser).toHaveBeenCalledWith({ target_ids: [bob.id] });
   });
diff --git a/src/components/Message/hooks/__tests__/useDeleteHandler.test.tsx b/src/components/Message/hooks/__tests__/useDeleteHandler.test.tsx
index 049c596b1d..25efba9fa3 100644
--- a/src/components/Message/hooks/__tests__/useDeleteHandler.test.tsx
+++ b/src/components/Message/hooks/__tests__/useDeleteHandler.test.tsx
@@ -89,15 +89,25 @@ describe('useDeleteHandler custom hook', () => {
     });
   });
 
-  it('should notify (and not throw) when the delete request fails', async () => {
+  it('should notify and throw when the delete request fails', async () => {
     vi.spyOn(channel.messageOperations, 'delete').mockRejectedValue(
       new Error('delete failed'),
     );
     const notify = vi.fn();
     const handleDelete = await renderUseDeleteHandler(testMessage, { notify });
     await act(async () => {
-      await expect(handleDelete()).resolves.toBeUndefined();
+      await expect(handleDelete()).rejects.toThrow('delete failed');
     });
     expect(notify).toHaveBeenCalledWith('Error deleting message', 'error');
   });
+
+  it('should throw when the delete request fails without notifications configured', async () => {
+    vi.spyOn(channel.messageOperations, 'delete').mockRejectedValue(
+      new Error('delete failed'),
+    );
+    const handleDelete = await renderUseDeleteHandler(testMessage);
+    await act(async () => {
+      await expect(handleDelete()).rejects.toThrow('delete failed');
+    });
+  });
 });
diff --git a/src/components/Message/hooks/__tests__/useMuteHandler.test.tsx b/src/components/Message/hooks/__tests__/useMuteHandler.test.tsx
index 56dde27e47..1a2b04e1a6 100644
--- a/src/components/Message/hooks/__tests__/useMuteHandler.test.tsx
+++ b/src/components/Message/hooks/__tests__/useMuteHandler.test.tsx
@@ -25,7 +25,10 @@ const mouseEventMock = fromPartial<React.BaseSyntheticEvent>({
 
 async function renderUseHandleMuteHook(
   message: LocalMessage | undefined = generateMessage() as MessageResponse & LocalMessage,
-  { mutes = [] as UserMuteResponse[] }: { mutes?: UserMuteResponse[] } = {},
+  {
+    mutes = [] as UserMuteResponse[],
+    withNotify = true,
+  }: { mutes?: UserMuteResponse[]; withNotify?: boolean } = {},
 ) {
   const client = await getTestClientWithUser(alice);
   client.moderation.mute = mute;
@@ -36,9 +39,12 @@ async function renderUseHandleMuteHook(
     <ChatProvider value={mockChatContext({ client })}>{children}</ChatProvider>
   );
 
-  const { result } = renderHook(() => useMuteHandler(message, { notify }), {
-    wrapper,
-  });
+  const { result } = renderHook(
+    () => useMuteHandler(message, withNotify ? { notify } : {}),
+    {
+      wrapper,
+    },
+  );
   return result.current;
 }
 
@@ -63,11 +69,11 @@ describe('useHandleMute custom hook', () => {
     expect(mute).toHaveBeenCalledWith({ target_ids: [bob.id] });
   });
 
-  it('should notify (and not throw) when muting a user fails', async () => {
+  it('should notify and throw when muting a user fails', async () => {
     const message = generateMessage({ user: bob }) as MessageResponse & LocalMessage;
     mute.mockImplementationOnce(() => Promise.reject(new Error('mute failed')));
     const handleMute = await renderUseHandleMuteHook(message);
-    await expect(handleMute(mouseEventMock)).resolves.toBeUndefined();
+    await expect(handleMute(mouseEventMock)).rejects.toThrow('mute failed');
     expect(mute).toHaveBeenCalledWith({ target_ids: [bob.id] });
     expect(notify).toHaveBeenCalledWith(expect.any(String), 'error');
   });
@@ -82,14 +88,31 @@ describe('useHandleMute custom hook', () => {
     expect(unmute).toHaveBeenCalledWith({ target_ids: [bob.id] });
   });
 
-  it('should notify (and not throw) when unmuting a user fails', async () => {
+  it('should notify and throw when unmuting a user fails', async () => {
     const message = generateMessage({ user: bob }) as MessageResponse & LocalMessage;
     unmute.mockImplementationOnce(() => Promise.reject(new Error('unmute failed')));
     const handleMute = await renderUseHandleMuteHook(message, {
       mutes: [fromPartial<UserMuteResponse>({ target: { id: bob.id } })],
     });
-    await expect(handleMute(mouseEventMock)).resolves.toBeUndefined();
+    await expect(handleMute(mouseEventMock)).rejects.toThrow('unmute failed');
     expect(unmute).toHaveBeenCalledWith({ target_ids: [bob.id] });
     expect(notify).toHaveBeenCalledWith(expect.any(String), 'error');
   });
+
+  it('should throw when muting a user fails without notifications configured', async () => {
+    const message = generateMessage({ user: bob }) as MessageResponse & LocalMessage;
+    mute.mockImplementationOnce(() => Promise.reject(new Error('mute failed')));
+    const handleMute = await renderUseHandleMuteHook(message, { withNotify: false });
+    await expect(handleMute(mouseEventMock)).rejects.toThrow('mute failed');
+  });
+
+  it('should throw when unmuting a user fails without notifications configured', async () => {
+    const message = generateMessage({ user: bob }) as MessageResponse & LocalMessage;
+    unmute.mockImplementationOnce(() => Promise.reject(new Error('unmute failed')));
+    const handleMute = await renderUseHandleMuteHook(message, {
+      mutes: [fromPartial<UserMuteResponse>({ target: { id: bob.id } })],
+      withNotify: false,
+    });
+    await expect(handleMute(mouseEventMock)).rejects.toThrow('unmute failed');
+  });
 });
diff --git a/src/components/Message/hooks/useDeleteHandler.ts b/src/components/Message/hooks/useDeleteHandler.ts
index a02d46a247..1101645bac 100644
--- a/src/components/Message/hooks/useDeleteHandler.ts
+++ b/src/components/Message/hooks/useDeleteHandler.ts
@@ -53,6 +53,7 @@ export const useDeleteHandler = (
             t('common.errorDeletingMessage.label', 'Error deleting message'),
           'error',
         );
+      throw e;
     }
   };
 };
diff --git a/src/components/Message/hooks/useMuteHandler.ts b/src/components/Message/hooks/useMuteHandler.ts
index 0f07f0fcec..9d86aa7785 100644
--- a/src/components/Message/hooks/useMuteHandler.ts
+++ b/src/components/Message/hooks/useMuteHandler.ts
@@ -49,13 +49,15 @@ export const useMuteHandler = (
 
         if (typeof successMessage === 'string') notify(successMessage, 'success');
       } catch (e) {
-        if (!notify) return;
-        const errorMessage =
-          (getErrorNotification &&
-            validateAndGetMessage(getErrorNotification, [message.user])) ||
-          t('common.errorMutingUser.label', 'Error muting a user ...');
-
-        if (typeof errorMessage === 'string') notify(errorMessage, 'error');
+        if (notify) {
+          const errorMessage =
+            (getErrorNotification &&
+              validateAndGetMessage(getErrorNotification, [message.user])) ||
+            t('common.errorMutingUser.label', 'Error muting a user ...');
+
+          if (typeof errorMessage === 'string') notify(errorMessage, 'error');
+        }
+        throw e;
       }
     } else {
       try {
@@ -71,13 +73,15 @@ export const useMuteHandler = (
 
         if (typeof successMessage === 'string') notify(successMessage, 'success');
       } catch (e) {
-        if (!notify) return;
-        const errorMessage =
-          (getErrorNotification &&
-            validateAndGetMessage(getErrorNotification, [message.user])) ||
-          t('common.errorUnmutingUser.label', 'Error unmuting a user ...');
-
-        if (typeof errorMessage === 'string') notify(errorMessage, 'error');
+        if (notify) {
+          const errorMessage =
+            (getErrorNotification &&
+              validateAndGetMessage(getErrorNotification, [message.user])) ||
+            t('common.errorUnmutingUser.label', 'Error unmuting a user ...');
+
+          if (typeof errorMessage === 'string') notify(errorMessage, 'error');
+        }
+        throw e;
       }
     }
   };

From 8ee1084c6474147c626809cbcd2e8e0addfbebc3 Mon Sep 17 00:00:00 2001
From: Oliver Lazoroski <oliver.lazoroski@gmail.com>
Date: Thu, 29 Oct 2026 14:27:34 +0100
Subject: [PATCH 5/5] fix(Message): skip pin rollback when a newer pin arrived

---
 .../hooks/__tests__/usePinHandler.test.tsx    | 29 +++++++++++++++++++
 src/components/Message/hooks/usePinHandler.ts | 11 +++++--
 2 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/src/components/Message/hooks/__tests__/usePinHandler.test.tsx b/src/components/Message/hooks/__tests__/usePinHandler.test.tsx
index 5d33e66a12..2d61bd2425 100644
--- a/src/components/Message/hooks/__tests__/usePinHandler.test.tsx
+++ b/src/components/Message/hooks/__tests__/usePinHandler.test.tsx
@@ -1,6 +1,7 @@
 import React from 'react';
 import { act, renderHook, type RenderHookResult } from '@testing-library/react';
 import { fromPartial } from '@total-typescript/shoehorn';
+import { nowNs } from 'stream-chat';
 import type { Channel as ChannelType, LocalMessage, StreamChat } from 'stream-chat';
 
 import { usePinHandler } from '../usePinHandler';
@@ -167,6 +168,34 @@ describe('usePinHandler custom hook', () => {
     expect(getStoredMessage(message.id)?.pinned_by).toEqual(newerPinner);
   });
 
+  it('should keep a newer pin with the same pinned value that arrived while pinning', async () => {
+    const rejectRequest = mockPendingRequest('pinMessage');
+    const newerPinner = generateUser();
+    const newerPinnedAt = nowNs();
+    const message = generateMessage({ cid: channel.cid, pinned: false }) as LocalMessage;
+    const { handlePin } = await renderUsePinHandler(message);
+    const pending = startHandlePin(handlePin);
+    act(() => {
+      channel.messagePaginator.ingestItem({
+        ...getStoredMessage(message.id)!,
+        pinned: true,
+        pinned_at: newerPinnedAt,
+        pinned_by: newerPinner,
+      });
+    });
+    await act(async () => {
+      rejectRequest(new Error('pin failed'));
+      await expect(pending).rejects.toThrow('pin failed');
+    });
+    expect(getStoredMessage(message.id)).toEqual(
+      expect.objectContaining({
+        pinned: true,
+        pinned_at: newerPinnedAt,
+        pinned_by: newerPinner,
+      }),
+    );
+  });
+
   it('should notify and throw when pinning fails with notifications configured', async () => {
     vi.spyOn(client, 'pinMessage').mockRejectedValue(new Error('pin failed'));
     const notify = vi.fn();
diff --git a/src/components/Message/hooks/usePinHandler.ts b/src/components/Message/hooks/usePinHandler.ts
index b22bfde932..8e86712b5e 100644
--- a/src/components/Message/hooks/usePinHandler.ts
+++ b/src/components/Message/hooks/usePinHandler.ts
@@ -54,11 +54,16 @@ export const usePinHandler = (
   const getLatestMessage = () => messagePaginator.getItem(message.id) ?? message;
 
   // Restores only the pin fields from before the click, so updates that arrived while the request
-  // was in flight (an edit, a reaction) are kept. Skipped when the pin state already changed
-  // again, since that change is newer than the snapshot.
+  // was in flight (an edit, a reaction) are kept. Skipped unless the stored pin is still the
+  // optimistic one: a pin or unpin that arrived meanwhile is newer than the snapshot, even when
+  // `pinned` has the same value.
   const rollBackPin = (optimisticMessage: LocalMessage) => {
     const latestMessage = messagePaginator.getItem(message.id);
-    if (!latestMessage || latestMessage.pinned !== optimisticMessage.pinned) return;
+    const isOptimisticPinStored =
+      latestMessage?.pinned === optimisticMessage.pinned &&
+      latestMessage.pinned_at === optimisticMessage.pinned_at &&
+      latestMessage.pinned_by?.id === optimisticMessage.pinned_by?.id;
+    if (!latestMessage || !isOptimisticPinStored) return;
 
     messagePaginator.ingestItem({
       ...latestMessage,