docs: add AI-agent migration guide for v8 → v9#3557
Merged
isekovanic merged 2 commits intodevelopfrom Apr 17, 2026
Merged
Conversation
… rename MessageMenu was left in the v9 public surface even though the overlay path no longer renders it; the source file carried a `// TODO: V9: Either remove this or refactor it` note. Delete the component, its DEFAULT_COMPONENTS entry, and its barrel re-export. The surrounding MessageMenu folder stays — MessageActionList, MessageActionListItem, MessageReactionPicker, and MessageUserReactions are the live replacements and remain overridable via WithComponents. Also finish the useAudioPlayerControl -> useAudioPlayer rename. The byte-identical `useAudioPlayer.ts` was already being imported directly by the internal callers (AudioAttachment, AudioRecordingPreview); only the barrel still pointed at the old name. Flip the barrel and delete the dead duplicate file.
Adds ai-docs/ai-migration.md — a compact (~4k token), machine-friendly migration reference for AI coding agents like Claude Code and Cursor. The human-oriented v8→v9 guide at https://getstream.io/chat/docs/sdk/react-native/basics/upgrading-from-v8/ is ~40k tokens and eats most of an agent's context window before work begins. This sibling doc strips rationale prose and keeps what agents actually need: rename bullets, detection/verification greps, decision rules for ambiguous cases, a machine-readable JSON rename block, and pointers into the installed SDK source under node_modules/stream-chat-react-native-core/src/. Key agent-oriented features: - §0 primer explicitly tells agents not to trust training data for v9 symbols (which predate v9) and names the correct node_modules path, since the installed package is `stream-chat-react-native-core`, not `stream-chat-react-native` (which is the bare-RN wrapper). - §1 detection greps let agents scope work by running a single rg pass and skipping sections whose patterns don't match. - §3 forces the three structural migrations first (WithComponents, 5 component renames, inverted audio semantics) because many leaf renames evaporate after the big moves. - §6 covers behavior changes that aren't pure renames (messageContentOrder default swap, deleted-message visibility, swipe-to-reply boundary, etc.) - §7 ships the full rename map as JSON for programmatic find/replace. - §9 gives agents a gate: rg + tsc commands that must come back clean before declaring done. Distribution: GitHub raw URL only — customers paste the link into their agent. Not added to the npm package's files array.
Base automatically changed from
refactor/v9-finish-message-menu-and-audio-hook
to
develop
April 17, 2026 11:23
isekovanic
approved these changes
Apr 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
ai-docs/ai-migration.md— a compact, machine-friendly v8 → v9 migration reference built for AI coding agents (Claude Code, Cursor, Copilot, etc.).The human-oriented v8 → v9 guide at https://getstream.io/chat/docs/sdk/react-native/basics/upgrading-from-v8/ is ~40k tokens. Loading it wholesale eats most of an agent's context window before any code work begins. This sibling doc is ~4k tokens (5× smaller) — prose rationale stripped, rename tables/decision rules/source pointers kept.
Customers point their agent at the raw GitHub URL. It is not shipped in the npm package.
Key agent-oriented features
node_modulespath — the installed package isstream-chat-react-native-core, notstream-chat-react-native(which is the bare-RN wrapper).rgpass and skip sections whose patterns don't match the customer codebase.WithComponents, 5 component renames, inverted audio semantics — done first because many leaf renames evaporate after the big moves.messageContentOrderdefault swap,deletedMessagesVisibilityTyperemoval, swipe-to-reply boundary,MessageActionType.typefield, etc.).rg+tsccommands that must come back clean before the agent declares done.Stacked on #3556
This PR targets
refactor/v9-finish-message-menu-and-audio-hookso the guide can accurately claimuseAudioPlayeris the v9 hook name andMessageMenuis removed. GitHub will auto-retarget todevelopwhen #3556 merges.Test plan
package/src/node_modules/path referenced exists underpackage/src/rgpattern is syntactically valid (no exit-2 from ripgrep)Related docs updates
Human migration guide edits (correcting the MessageMenu and AudioAttachment claims that this agent guide is also correcting) are a separate PR in the
docs-contentrepo.