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

---
 .../hooks/__tests__/usePinHandler.test.tsx    | 94 +++++++++++++++++++
 src/components/Message/hooks/usePinHandler.ts |  6 +-
 2 files changed, 98 insertions(+), 2 deletions(-)
 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..fa8f20693a
--- /dev/null
+++ b/src/components/Message/hooks/__tests__/usePinHandler.test.tsx
@@ -0,0 +1,94 @@
+import React from 'react';
+import { renderHook } from '@testing-library/react';
+import { fromPartial } from '@total-typescript/shoehorn';
+
+import { usePinHandler } from '../usePinHandler';
+
+import { ChannelActionProvider } from '../../../../context/ChannelActionContext';
+import { ChannelStateProvider } from '../../../../context/ChannelStateContext';
+import { ChatProvider } from '../../../../context/ChatContext';
+import {
+  generateChannel,
+  generateMessage,
+  generateUser,
+  getTestClientWithUser,
+  mockChannelActionContext,
+  mockChannelStateContext,
+  mockChatContext,
+} from '../../../../mock-builders';
+import type { LocalMessage, MessageResponse } from 'stream-chat';
+
+const alice = generateUser({ name: 'alice' });
+const pinMessage = vi.fn();
+const unpinMessage = vi.fn();
+const updateMessage = vi.fn();
+const mouseEventMock = fromPartial<React.BaseSyntheticEvent>({
+  preventDefault: vi.fn(() => {}),
+});
+
+async function renderUsePinHandlerHook(message: LocalMessage) {
+  const client = await getTestClientWithUser(alice);
+  client.pinMessage = pinMessage;
+  client.unpinMessage = unpinMessage;
+  const channel = generateChannel();
+
+  const wrapper = ({ children }: { children?: React.ReactNode }) => (
+    <ChatProvider value={mockChatContext({ client })}>
+      <ChannelActionProvider value={mockChannelActionContext({ updateMessage })}>
+        <ChannelStateProvider
+          value={mockChannelStateContext({
+            channel,
+            channelCapabilities: { 'pin-message': true },
+          })}
+        >
+          {children}
+        </ChannelStateProvider>
+      </ChannelActionProvider>
+    </ChatProvider>
+  );
+
+  const { result } = renderHook(() => usePinHandler(message), { wrapper });
+  return result.current;
+}
+
+describe('usePinHandler custom hook', () => {
+  afterEach(vi.clearAllMocks);
+
+  it('should pin the message and update it optimistically', async () => {
+    const message = generateMessage({ pinned: false }) as MessageResponse & LocalMessage;
+    const { handlePin } = await renderUsePinHandlerHook(message);
+    await handlePin(mouseEventMock);
+    expect(pinMessage).toHaveBeenCalledWith(message);
+    expect(updateMessage).toHaveBeenCalledTimes(1);
+    expect(updateMessage).toHaveBeenCalledWith(expect.objectContaining({ pinned: true }));
+  });
+
+  it('should roll back and throw when pinning fails', async () => {
+    const message = generateMessage({ pinned: false }) as MessageResponse & LocalMessage;
+    pinMessage.mockImplementationOnce(() => Promise.reject(new Error('pin failed')));
+    const { handlePin } = await renderUsePinHandlerHook(message);
+    await expect(handlePin(mouseEventMock)).rejects.toThrow('pin failed');
+    expect(updateMessage).toHaveBeenCalledTimes(2);
+    expect(updateMessage).toHaveBeenLastCalledWith(message);
+  });
+
+  it('should unpin the message and update it optimistically', async () => {
+    const message = generateMessage({ pinned: true }) as MessageResponse & LocalMessage;
+    const { handlePin } = await renderUsePinHandlerHook(message);
+    await handlePin(mouseEventMock);
+    expect(unpinMessage).toHaveBeenCalledWith(message);
+    expect(updateMessage).toHaveBeenCalledTimes(1);
+    expect(updateMessage).toHaveBeenCalledWith(
+      expect.objectContaining({ pinned: false }),
+    );
+  });
+
+  it('should roll back and throw when unpinning fails', async () => {
+    const message = generateMessage({ pinned: true }) as MessageResponse & LocalMessage;
+    unpinMessage.mockImplementationOnce(() => Promise.reject(new Error('unpin failed')));
+    const { handlePin } = await renderUsePinHandlerHook(message);
+    await expect(handlePin(mouseEventMock)).rejects.toThrow('unpin failed');
+    expect(updateMessage).toHaveBeenCalledTimes(2);
+    expect(updateMessage).toHaveBeenLastCalledWith(message);
+  });
+});
diff --git a/src/components/Message/hooks/usePinHandler.ts b/src/components/Message/hooks/usePinHandler.ts
index 6e9094eae2..49fc4decb9 100644
--- a/src/components/Message/hooks/usePinHandler.ts
+++ b/src/components/Message/hooks/usePinHandler.ts
@@ -29,8 +29,9 @@ export const usePinHandler = (message: LocalMessage) => {
         updateMessage(optimisticMessage);
 
         await client.pinMessage(message);
-      } catch (e) {
+      } catch (error) {
         updateMessage(message);
+        throw error;
       }
     } else {
       try {
@@ -45,8 +46,9 @@ export const usePinHandler = (message: LocalMessage) => {
         updateMessage(optimisticMessage);
 
         await client.unpinMessage(message);
-      } catch (e) {
+      } catch (error) {
         updateMessage(message);
+        throw error;
       }
     }
   };

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

---
 .../vite/src/CustomMessageUi/variants.tsx     |  11 +-
 .../hooks/__tests__/usePinHandler.test.tsx    | 154 +++++++++++++-----
 src/components/Message/hooks/usePinHandler.ts |  56 +++++--
 src/context/MessageContext.tsx                |   2 +-
 4 files changed, 160 insertions(+), 63 deletions(-)

diff --git a/examples/vite/src/CustomMessageUi/variants.tsx b/examples/vite/src/CustomMessageUi/variants.tsx
index e0e8866d79..c2815c5f85 100644
--- a/examples/vite/src/CustomMessageUi/variants.tsx
+++ b/examples/vite/src/CustomMessageUi/variants.tsx
@@ -246,7 +246,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 fa8f20693a..ba3fb09f86 100644
--- a/src/components/Message/hooks/__tests__/usePinHandler.test.tsx
+++ b/src/components/Message/hooks/__tests__/usePinHandler.test.tsx
@@ -1,5 +1,5 @@
 import React from 'react';
-import { renderHook } from '@testing-library/react';
+import { act, renderHook } from '@testing-library/react';
 import { fromPartial } from '@total-typescript/shoehorn';
 
 import { usePinHandler } from '../usePinHandler';
@@ -8,7 +8,6 @@ import { ChannelActionProvider } from '../../../../context/ChannelActionContext'
 import { ChannelStateProvider } from '../../../../context/ChannelStateContext';
 import { ChatProvider } from '../../../../context/ChatContext';
 import {
-  generateChannel,
   generateMessage,
   generateUser,
   getTestClientWithUser,
@@ -16,22 +15,24 @@ import {
   mockChannelStateContext,
   mockChatContext,
 } from '../../../../mock-builders';
-import type { LocalMessage, MessageResponse } from 'stream-chat';
+import type { Channel, LocalMessage, StreamChat } from 'stream-chat';
+
+// `usePinHandler` updates the message optimistically through `updateMessage`, 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.
 
 const alice = generateUser({ name: 'alice' });
-const pinMessage = vi.fn();
-const unpinMessage = vi.fn();
-const updateMessage = vi.fn();
+let client: StreamChat;
+let channel: Channel;
+// Writes to the channel state like `Channel`'s own `updateMessage`, so tests can read it back.
+const updateMessage = vi.fn((message: LocalMessage) =>
+  channel.state.addMessageSorted(message, true),
+);
 const mouseEventMock = fromPartial<React.BaseSyntheticEvent>({
   preventDefault: vi.fn(() => {}),
 });
 
-async function renderUsePinHandlerHook(message: LocalMessage) {
-  const client = await getTestClientWithUser(alice);
-  client.pinMessage = pinMessage;
-  client.unpinMessage = unpinMessage;
-  const channel = generateChannel();
-
+function renderUsePinHandlerHook(message: LocalMessage) {
   const wrapper = ({ children }: { children?: React.ReactNode }) => (
     <ChatProvider value={mockChatContext({ client })}>
       <ChannelActionProvider value={mockChannelActionContext({ updateMessage })}>
@@ -51,44 +52,111 @@ async function renderUsePinHandlerHook(message: LocalMessage) {
   return result.current;
 }
 
+// Adds a message to the channel state and returns it as stored, like the message a
+// `Message` component renders with.
+const seedMessage = (overrides: Parameters<typeof generateMessage>[0]) => {
+  const message = generateMessage(overrides);
+  channel.state.addMessageSorted(message, true);
+  return getStoredMessage(message.id)!;
+};
+
+const getStoredMessage = (id: string) => channel.state.findMessage(id);
+
+// 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;
+};
+
 describe('usePinHandler custom hook', () => {
-  afterEach(vi.clearAllMocks);
-
-  it('should pin the message and update it optimistically', async () => {
-    const message = generateMessage({ pinned: false }) as MessageResponse & LocalMessage;
-    const { handlePin } = await renderUsePinHandlerHook(message);
-    await handlePin(mouseEventMock);
-    expect(pinMessage).toHaveBeenCalledWith(message);
-    expect(updateMessage).toHaveBeenCalledTimes(1);
-    expect(updateMessage).toHaveBeenCalledWith(expect.objectContaining({ pinned: true }));
+  beforeAll(async () => {
+    client = await getTestClientWithUser(alice);
+    channel = client.channel('messaging', 'pin-handler-test');
   });
 
-  it('should roll back and throw when pinning fails', async () => {
-    const message = generateMessage({ pinned: false }) as MessageResponse & LocalMessage;
-    pinMessage.mockImplementationOnce(() => Promise.reject(new Error('pin failed')));
-    const { handlePin } = await renderUsePinHandlerHook(message);
-    await expect(handlePin(mouseEventMock)).rejects.toThrow('pin failed');
-    expect(updateMessage).toHaveBeenCalledTimes(2);
-    expect(updateMessage).toHaveBeenLastCalledWith(message);
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.clearAllMocks();
   });
 
-  it('should unpin the message and update it optimistically', async () => {
-    const message = generateMessage({ pinned: true }) as MessageResponse & LocalMessage;
-    const { handlePin } = await renderUsePinHandlerHook(message);
-    await handlePin(mouseEventMock);
-    expect(unpinMessage).toHaveBeenCalledWith(message);
-    expect(updateMessage).toHaveBeenCalledTimes(1);
-    expect(updateMessage).toHaveBeenCalledWith(
-      expect.objectContaining({ pinned: false }),
+  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 = seedMessage({ pinned });
+      const { handlePin } = renderUsePinHandlerHook(message);
+      await handlePin(mouseEventMock);
+      expect(requestSpy).toHaveBeenCalledWith(message);
+      expect(getStoredMessage(message.id)).toEqual(
+        expect.objectContaining({ pinned: !pinned }),
+      );
+    },
+  );
+
+  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 = seedMessage({ pinned });
+      const { handlePin } = renderUsePinHandlerHook(message);
+      const pending = startHandlePin(handlePin);
+      expect(getStoredMessage(message.id)).toEqual(
+        expect.objectContaining({ pinned: !pinned }),
+      );
+      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 = seedMessage({ pinned: false, text: 'original' });
+    const { handlePin } = renderUsePinHandlerHook(message);
+    const pending = startHandlePin(handlePin);
+    channel.state.addMessageSorted(
+      { ...getStoredMessage(message.id)!, text: 'edited while pinning' },
+      true,
+    );
+    rejectRequest(new Error('pin failed'));
+    await expect(pending).rejects.toThrow('pin failed');
+    expect(getStoredMessage(message.id)).toEqual(
+      expect.objectContaining({ pinned: false, text: 'edited while pinning' }),
     );
   });
 
-  it('should roll back and throw when unpinning fails', async () => {
-    const message = generateMessage({ pinned: true }) as MessageResponse & LocalMessage;
-    unpinMessage.mockImplementationOnce(() => Promise.reject(new Error('unpin failed')));
-    const { handlePin } = await renderUsePinHandlerHook(message);
-    await expect(handlePin(mouseEventMock)).rejects.toThrow('unpin failed');
-    expect(updateMessage).toHaveBeenCalledTimes(2);
-    expect(updateMessage).toHaveBeenLastCalledWith(message);
+  it('should keep a pin state that changed while the request was pending', async () => {
+    const rejectRequest = mockPendingRequest('unpinMessage');
+    const newerPinner = generateUser();
+    const message = seedMessage({ pinned: true, pinned_by: generateUser() });
+    const { handlePin } = renderUsePinHandlerHook(message);
+    const pending = startHandlePin(handlePin);
+    channel.state.addMessageSorted(
+      { ...getStoredMessage(message.id)!, pinned: true, pinned_by: newerPinner },
+      true,
+    );
+    rejectRequest(new Error('unpin failed'));
+    await expect(pending).rejects.toThrow('unpin failed');
+    expect(getStoredMessage(message.id)?.pinned_by).toEqual(newerPinner);
   });
 });
diff --git a/src/components/Message/hooks/usePinHandler.ts b/src/components/Message/hooks/usePinHandler.ts
index 49fc4decb9..d0820d558a 100644
--- a/src/components/Message/hooks/usePinHandler.ts
+++ b/src/components/Message/hooks/usePinHandler.ts
@@ -7,47 +7,67 @@ import type { ReactEventHandler } from '../types';
 
 export const usePinHandler = (message: LocalMessage) => {
   const { updateMessage } = useChannelActionContext('usePinHandler');
-  const { channelCapabilities = {} } = useChannelStateContext('usePinHandler');
+  const { channel, channelCapabilities = {} } = useChannelStateContext('usePinHandler');
   const { client } = useChatContext('usePinHandler');
 
   const canPin = !!channelCapabilities['pin-message'];
 
+  // The stored message, which may be newer than the `message` this hook rendered with.
+  const getLatestMessage = () =>
+    channel.state.findMessage(message.id, message.parent_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 = channel.state.findMessage(message.id, message.parent_id);
+    if (!latestMessage || latestMessage.pinned !== optimisticMessage.pinned) return;
+
+    updateMessage({
+      ...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: new Date(),
-          pinned_by: client.user,
-        };
+      const optimisticMessage: LocalMessage = {
+        ...getLatestMessage(),
+        pinned: true,
+        pinned_at: new Date(),
+        pinned_by: client.user,
+      };
 
+      try {
         updateMessage(optimisticMessage);
 
         await client.pinMessage(message);
       } catch (error) {
-        updateMessage(message);
+        rollBackPin(optimisticMessage);
         throw error;
       }
     } else {
-      try {
-        const optimisticMessage = {
-          ...message,
-          pin_expires: null,
-          pinned: false,
-          pinned_at: null,
-          pinned_by: null,
-        };
+      const optimisticMessage: LocalMessage = {
+        ...getLatestMessage(),
+        pin_expires: null,
+        pinned: false,
+        pinned_at: null,
+        pinned_by: null,
+      };
 
+      try {
         updateMessage(optimisticMessage);
 
         await client.unpinMessage(message);
       } catch (error) {
-        updateMessage(message);
+        rollBackPin(optimisticMessage);
         throw error;
       }
     }
diff --git a/src/context/MessageContext.tsx b/src/context/MessageContext.tsx
index a16a8920ef..04a01576da 100644
--- a/src/context/MessageContext.tsx
+++ b/src/context/MessageContext.tsx
@@ -45,7 +45,7 @@ export type MessageContextValue = {
   handleMute: ReactEventHandler;
   /** Function to open a Thread on a Message */
   handleOpenThread: ReactEventHandler;
-  /** Function to pin a Message in a Channel */
+  /** Function to pin or unpin a Message in a Channel. Rejects with the request's error when it fails, after rolling back. */
   handlePin: ReactEventHandler;
   /** Function to post a reaction on a Message */
   handleReaction: (

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

---
 .../hooks/__tests__/usePinHandler.test.tsx    | 26 +++++++++++++++++++
 src/components/Message/hooks/usePinHandler.ts | 19 +++++++++++---
 2 files changed, 42 insertions(+), 3 deletions(-)

diff --git a/src/components/Message/hooks/__tests__/usePinHandler.test.tsx b/src/components/Message/hooks/__tests__/usePinHandler.test.tsx
index ba3fb09f86..d4b129e3b7 100644
--- a/src/components/Message/hooks/__tests__/usePinHandler.test.tsx
+++ b/src/components/Message/hooks/__tests__/usePinHandler.test.tsx
@@ -159,4 +159,30 @@ describe('usePinHandler custom hook', () => {
     await expect(pending).rejects.toThrow('unpin failed');
     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 = new Date(Date.now() + 60_000);
+    const message = seedMessage({ pinned: false });
+    const { handlePin } = renderUsePinHandlerHook(message);
+    const pending = startHandlePin(handlePin);
+    channel.state.addMessageSorted(
+      {
+        ...getStoredMessage(message.id)!,
+        pinned: true,
+        pinned_at: newerPinnedAt,
+        pinned_by: newerPinner,
+      },
+      true,
+    );
+    rejectRequest(new Error('pin failed'));
+    await expect(pending).rejects.toThrow('pin failed');
+    expect(getStoredMessage(message.id)).toEqual(
+      expect.objectContaining({ pinned: true, pinned_by: newerPinner }),
+    );
+    expect(getStoredMessage(message.id)?.pinned_at?.getTime()).toBe(
+      newerPinnedAt.getTime(),
+    );
+  });
 });
diff --git a/src/components/Message/hooks/usePinHandler.ts b/src/components/Message/hooks/usePinHandler.ts
index d0820d558a..e6aadf87c7 100644
--- a/src/components/Message/hooks/usePinHandler.ts
+++ b/src/components/Message/hooks/usePinHandler.ts
@@ -5,6 +5,11 @@ import { useChatContext } from '../../../context/ChatContext';
 import type { LocalMessage } from 'stream-chat';
 import type { ReactEventHandler } from '../types';
 
+// `pinned_at` is a `Date` here, and a copy of the message from an event carries its own instance,
+// so pins are compared by time rather than by reference.
+const getPinnedAtTime = (pinnedAt: LocalMessage['pinned_at']) =>
+  pinnedAt ? new Date(pinnedAt).getTime() : undefined;
+
 export const usePinHandler = (message: LocalMessage) => {
   const { updateMessage } = useChannelActionContext('usePinHandler');
   const { channel, channelCapabilities = {} } = useChannelStateContext('usePinHandler');
@@ -17,11 +22,19 @@ export const usePinHandler = (message: LocalMessage) => {
     channel.state.findMessage(message.id, message.parent_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 = channel.state.findMessage(message.id, message.parent_id);
-    if (!latestMessage || latestMessage.pinned !== optimisticMessage.pinned) return;
+    if (!latestMessage) return;
+
+    const isOptimisticPinStored =
+      latestMessage.pinned === optimisticMessage.pinned &&
+      getPinnedAtTime(latestMessage.pinned_at) ===
+        getPinnedAtTime(optimisticMessage.pinned_at) &&
+      latestMessage.pinned_by?.id === optimisticMessage.pinned_by?.id;
+    if (!isOptimisticPinStored) return;
 
     updateMessage({
       ...latestMessage,