feat: llc new state layer

ai-docs/ai-migration-v9-to-v10.md

@@ -0,0 +1,193 @@
+# stream-chat-react-native v9 → v10 — Agent Migration Guide
+
+> Machine-oriented migration reference for AI coding agents, mirroring the style
+> of `ai-migration.md` (v8 → v9). **WORK IN PROGRESS.** v10 adopts the
+> `stream-chat` v10 reactive state layer (instance-owned `StateStore`s +
+> `messagePaginator`). This file currently documents the **context-teardown
+> breaking changes** that have shipped; more v10 changes (optimistic-ops
+> migration, targeting, unread-state) are not yet landed and will be appended.
+
+## 0. For the agent (read first)
+
+1. **Your training data predates v10.** Do not rely on memory for v10 symbols or
+   export paths. Verify against the installed SDK source under
+   `node_modules/stream-chat-react-native-core/src/`.
+2. **The unifying idea:** state that used to be copied into React context is now
+   read reactively from `stream-chat` instance stores via the SDK hook
+   `useStateStore(store, selector)`. The channel exposes per-concern stores on
+   `channel.state.*` and a message paginator on `channel.messagePaginator`.
+3. **Resolution hooks** (already present since early v10):
+   - `useChannelContext().channel` — the active `Channel` instance.
+   - `useMessagePaginator()` — `threadInstance?.messagePaginator ?? channel.messagePaginator`.
+   - `useStateStore(store, selector)` — subscribe to a `StateStore` with a
+     memo-stable selector (return a stable object; do not allocate fresh arrays
+     inside the selector).
+4. **Detect before editing.** Run §1; skip any section with zero hits.
+
+## 1. Detection (run first)
+
+Run each ripgrep against the customer's app source root. Zero hits = skip.
+
+```bash
+# §2 — TypingContext removed
+rg '\b(useTypingContext|TypingProvider|TypingContext|TypingContextValue|useCreateTypingContext)\b' src/
+
+# §3 — ChannelContext scalar fields removed
+rg 'useChannelContext\(\)' -A6 src/ | rg '\b(members|read|watchers|watcherCount)\b'
+
+# §4 — PaginatedMessageListContext removed
+rg '\b(usePaginatedMessageListContext|PaginatedMessageListProvider|PaginatedMessageListContextValue|useCreatePaginatedMessageListContext)\b' src/
+
+# §5 — custom FooterComponent / HeaderComponent reading loadingMore from context
+rg '\b(FooterComponent|HeaderComponent)\b' src/
+```
+
+## 2. `TypingContext` removed → `channel.state.typingStore`
+
+Removed symbols: `TypingContext`, `TypingProvider`, `useTypingContext`,
+`TypingContextValue`, `useCreateTypingContext`.
+
+**Before (v9):**
+
+```tsx
+import { useTypingContext } from 'stream-chat-react-native';
+
+const { typing } = useTypingContext();
+```
+
+**After (v10):**
+
+```tsx
+import { useChannelContext, useStateStore } from 'stream-chat-react-native';
+import type { TypingUsersState } from 'stream-chat';
+
+const typingSelector = (state: TypingUsersState) => ({ typing: state.typing });
+
+const { channel } = useChannelContext();
+const { typing } = useStateStore(channel.state.typingStore, typingSelector) ?? { typing: {} };
+```
+
+`typing` has the same shape as before (`Record<string, Event>`).
+
+## 3. `ChannelContext` scalar state fields removed → `channel.state.*Store`
+
+`useChannelContext()` no longer returns `members`, `read`, `watchers`, or
+`watcherCount`. Read them from the per-channel stores.
+
+| Removed context field | Replacement store | Store state key |
+|---|---|---|
+| `members` | `channel.state.membersStore` | `members` |
+| `read` | `channel.state.readStore` | `read` |
+| `watchers` | `channel.state.watcherStore` | `watchers` |
+| `watcherCount` | `channel.state.watcherStore` | `watcherCount` |
+
+**Before (v9):**
+
+```tsx
+const { members, watcherCount } = useChannelContext();
+```
+
+**After (v10):**
+
+```tsx
+import { useChannelContext, useStateStore } from 'stream-chat-react-native';
+import type { MembersState, WatcherState } from 'stream-chat';
+
+const membersSelector = (s: MembersState) => ({ members: s.members });
+const watcherSelector = (s: WatcherState) => ({
+  watcherCount: s.watcherCount,
+  watchers: s.watchers,
+});
+
+const { channel } = useChannelContext();
+const { members } = useStateStore(channel.state.membersStore, membersSelector) ?? { members: {} };
+const { watcherCount } = useStateStore(channel.state.watcherStore, watcherSelector) ?? {};
+```
+
+Note: `members` remains available on the per-message `MessageContext`
+(`useMessageContext().members`) for message-level consumers such as a custom
+message footer — only the **channel-level** `ChannelContext.members` was removed.
+
+## 4. `PaginatedMessageListContext` removed → `useMessagePaginator()` / `channel.messagePaginator`
+
+Removed symbols: `PaginatedMessageListContext`, `PaginatedMessageListProvider`,
+`usePaginatedMessageListContext`, `PaginatedMessageListContextValue`,
+`useCreatePaginatedMessageListContext`.
+
+The message-list state (messages / hasMore / loading) now lives on the paginator.
+**Direction mapping** (non-obvious): the paginator is bi-directional — `tail` =
+older messages, `head` = newer.
+
+| Removed context field | Replacement |
+|---|---|
+| `messages` | `channel.messagePaginator.state.items` |
+| `hasMore` (older) | `channel.messagePaginator.state.hasMoreTail` |
+| `hasMoreNewer` | `channel.messagePaginator.state.hasMoreHead` |
+| `loading` | `channel.messagePaginator.state.isLoading` |
+| `loadMore()` (older) | `channel.messagePaginator.toTail()` |
+| `loadMoreRecent()` (newer) | `channel.messagePaginator.toHead()` |
+| `loadLatestMessages()` | `channel.messagePaginator.jumpToTheLatestMessage()` |
+
+**Before (v9):**
+
+```tsx
+const { messages, hasMore, loadMore } = usePaginatedMessageListContext();
+```
+
+**After (v10):**
+
+```tsx
+import { useChannelContext, useStateStore } from 'stream-chat-react-native';
+import type { LocalMessage } from 'stream-chat';
+
+const selector = (s: { items?: LocalMessage[]; hasMoreTail: boolean }) => ({
+  messages: s.items,
+  hasMore: s.hasMoreTail,
+});
+
+const { channel } = useChannelContext();
+const { messages, hasMore } = useStateStore(channel.messagePaginator.state, selector) ?? {};
+const loadMore = () => channel.messagePaginator.toTail();
+```
+
+Use `channel.messagePaginator` for the channel message list. For thread replies,
+use `useMessagePaginator()` (thread-aware) — but note the **main** channel list
+must read `channel.messagePaginator` directly so it keeps showing channel
+messages while a thread is open.
+
+## 5. Custom `FooterComponent` / `HeaderComponent` receive `loadingMore` as a prop
+
+The inline loading indicators no longer read `loadingMore` /
+`loadingMoreRecent` from `PaginatedMessageListContext`; the list owns those flags
+and passes them as props. If you override the message list's loading indicator:
+
+- **`MessageList`** (inverted): custom `FooterComponent` now receives
+  `{ loadingMore?: boolean }` as a prop.
+- **`MessageFlashList`**: custom `HeaderComponent` now receives
+  `{ loadingMore?: boolean }` as a prop.
+
+**Before (v9):**
+
+```tsx
+const MyFooter = () => {
+  const { loadingMore } = usePaginatedMessageListContext();
+  return loadingMore ? <Spinner /> : null;
+};
+```
+
+**After (v10):**
+
+```tsx
+const MyFooter = ({ loadingMore }: { loadingMore?: boolean }) =>
+  loadingMore ? <Spinner /> : null;
+```
+
+No-prop override components remain assignable (the prop is optional), so
+overrides that don't read the flag need no change.
+
+## 6. Verify
+
+- Typecheck the customer app; the removed symbols surface as
+  "Property does not exist" / "Cannot find name" errors — fix each per §2–§5.
+- Run the app: typing indicator, member/watcher counts, message-list scroll
+  pagination (both directions), and any custom loading-indicator override.

examples/ExpoMessaging/app/channel/[cid]/index.tsx

@@ -10,7 +10,6 @@ import {
   ChannelAvatar,
   MessageComposer,
   MessageList,
-  ThreadContextValue,
   useChannelPreviewDisplayName,
   useChatContext,
 } from 'stream-chat-expo';
@@ -110,7 +109,7 @@ export default function ChannelScreen() {
         messageId={messageId}
       >
         <MessageList
-          onThreadSelect={(thread: ThreadContextValue['thread']) => {
+          onThreadSelect={(thread) => {
             setThread(thread);
             router.push(`/channel/${channel.cid}/thread/${thread?.cid ?? ''}`);
           }}

examples/ExpoMessaging/context/AppContext.tsx

@@ -1,13 +1,12 @@
 import React, { PropsWithChildren, createContext, useState } from 'react';
 
-import { Channel as ChannelType } from 'stream-chat';
-import { ThreadContextValue } from 'stream-chat-expo';
+import { Channel as ChannelType, LocalMessage } from 'stream-chat';
 
 export type AppContextType = {
   channel: ChannelType | undefined;
   setChannel: React.Dispatch<React.SetStateAction<ChannelType | undefined>>;
-  setThread: React.Dispatch<React.SetStateAction<ThreadContextValue['thread'] | undefined>>;
-  thread: ThreadContextValue['thread'] | undefined;
+  setThread: React.Dispatch<React.SetStateAction<LocalMessage | null | undefined>>;
+  thread: LocalMessage | null | undefined;
 };
 
 export const AppContext = createContext<AppContextType>({
@@ -19,7 +18,7 @@ export const AppContext = createContext<AppContextType>({
 
 export const AppProvider = ({ children }: PropsWithChildren) => {
   const [channel, setChannel] = useState<ChannelType | undefined>(undefined);
-  const [thread, setThread] = useState<ThreadContextValue['thread'] | undefined>(undefined);
+  const [thread, setThread] = useState<LocalMessage | null | undefined>(undefined);
 
   return (
     <AppContext.Provider value={{ channel, setChannel, thread, setThread }}>

examples/SampleApp/metro.config.js

@@ -19,6 +19,9 @@ const metroExclusionList = require(
 const exclusionList = metroExclusionList.default || metroExclusionList;
 const packageDirPath = PATH.resolve(__dirname, '../../package');
 const nativePackageDirPath = PATH.resolve(__dirname, '../../package/native-package');
+// Local checkout of stream-chat-js (portaled via root package.json `resolutions`).
+// Metro needs the path explicitly — it does not honor Yarn's portal symlink for native bundling.
+const streamChatLocalPath = '/Users/isekovanic/Projects/stream-chat-js';
 
 const symlinked = {
   'stream-chat-react-native': nativePackageDirPath,
@@ -65,17 +68,20 @@ const uniqueModules = dependencyPackageNames.map((packageName) => {
 const blockList = uniqueModules.map(({ blockPattern }) => blockPattern);
 
 // provide the path for the unique modules
-const extraNodeModules = uniqueModules.reduce((acc, item) => {
-  acc[item.packageName] = item.modulePath;
-  return acc;
-}, {});
+const extraNodeModules = uniqueModules.reduce(
+  (acc, item) => {
+    acc[item.packageName] = item.modulePath;
+    return acc;
+  },
+  { 'stream-chat': streamChatLocalPath },
+);
 
 config.resolver.blockList = exclusionList(blockList);
 config.resolver.extraNodeModules = extraNodeModules;
 
 config.resolver.nodeModulesPaths = [PATH.resolve(__dirname, 'node_modules')];
 
 // add the package dir for metro to access the package folder
-config.watchFolders = [packageDirPath];
+config.watchFolders = [packageDirPath, streamChatLocalPath];
 
 module.exports = config;

examples/SampleApp/src/components/UnreadCountBadge.tsx

@@ -23,28 +23,31 @@ export const ChannelsUnreadCountBadge: React.FC = () => {
   const { chatClient } = useAppContext();
   const [unreadCount, setUnreadCount] = useState<number>(0);
   /**
-   * Listen to changes in unread counts and update the badge count
+   * Listen to changes in unread counts and update the badge count.
+   *
+   * We deliberately derive the total from each channel's local `countUnread()` (a sum over the
+   * loaded/active channels) rather than the server-sent `event.total_unread_count`. The local count
+   * respects the "viewing live" gate — the channel the user is currently reading at the bottom stays
+   * at 0 — so the badge does NOT flicker when a message arrives in the active channel. The server
+   * total, by contrast, briefly counts that message until the mark-read round-trips.
    */
   useEffect(() => {
-    const listener = chatClient?.on((e) => {
-      const event = e.me ?? e;
-      if (event.total_unread_count !== undefined) {
-        setUnreadCount(event.total_unread_count);
-      } else {
-        if (Object.keys(chatClient?.activeChannels).length > 0) {
-          const countUnread = Object.values(chatClient.activeChannels).reduce(
-            (count, channel) => count + channel.countUnread(),
-            0,
-          );
-          setUnreadCount(countUnread);
-        }
-      }
+    if (!chatClient) {
+      return;
+    }
+    const computeUnreadCount = () =>
+      Object.values(chatClient.activeChannels).reduce(
+        (count, channel) => count + (channel?.countUnread() ?? 0),
+        0,
+      );
+
+    setUnreadCount(computeUnreadCount());
+    const listener = chatClient.on(() => {
+      setUnreadCount(computeUnreadCount());
     });
 
     return () => {
-      if (listener) {
-        listener.unsubscribe();
-      }
+      listener.unsubscribe();
     };
   }, [chatClient]);
 

examples/SampleApp/src/context/StreamChatContext.tsx

@@ -1,14 +1,13 @@
 import React from 'react';
 import { PropsWithChildren, createContext, useState } from 'react';
 
-import { Channel as ChannelType } from 'stream-chat';
-import { ThreadContextValue } from 'stream-chat-react-native';
+import { Channel as ChannelType, LocalMessage } from 'stream-chat';
 
 export type StreamChatContextType = {
   channel: ChannelType | undefined;
   setChannel: React.Dispatch<React.SetStateAction<ChannelType | undefined>>;
-  setThread: React.Dispatch<React.SetStateAction<ThreadContextValue['thread'] | undefined>>;
-  thread: ThreadContextValue['thread'] | undefined;
+  setThread: React.Dispatch<React.SetStateAction<LocalMessage | null | undefined>>;
+  thread: LocalMessage | null | undefined;
 };
 
 export const StreamChatContext = createContext<StreamChatContextType>({
@@ -20,7 +19,7 @@ export const StreamChatContext = createContext<StreamChatContextType>({
 
 export const StreamChatProvider = ({ children }: PropsWithChildren) => {
   const [channel, setChannel] = useState<ChannelType | undefined>(undefined);
-  const [thread, setThread] = useState<ThreadContextValue['thread'] | undefined>(undefined);
+  const [thread, setThread] = useState<LocalMessage | null | undefined>(undefined);
 
   return (
     <StreamChatContext.Provider value={{ channel, setChannel, thread, setThread }}>

examples/SampleApp/src/screens/ChannelScreen.tsx

@@ -11,7 +11,6 @@ import {
   MessageComposer,
   MessageList,
   MessageFlashList,
-  ThreadContextValue,
   useAttachmentPickerContext,
   useChannelPreviewDisplayName,
   useChatContext,
@@ -130,7 +129,7 @@ export const ChannelScreen: React.FC<ChannelScreenProps> = ({ navigation, route
 
   const [channel, setChannel] = useState<StreamChatChannel | undefined>(channelFromProp);
 
-  const [selectedThread, setSelectedThread] = useState<ThreadContextValue['thread']>();
+  const [selectedThread, setSelectedThread] = useState<LocalMessage | null>();
 
   useEffect(() => {
     const initChannel = async () => {