Merge pull request #933 from pangeachat/docs/explain-why-grapheme-cluster-is-important

explain why using grapheme clustering is important

lib/pangea/widgets/chat/overlay_message_text.dart

@@ -75,6 +75,11 @@ class OverlayMessageTextState extends State<OverlayMessageText> {
         widget.pangeaMessageEvent.messageDisplayText.characters;
 
     // When building token positions, use grapheme cluster indices
+    // We use grapheme cluster indices to avoid splitting emojis and other
+    // complex characters that requires multiple code units.
+    // For instance, the emoji 🇺🇸 is represented by two code units:
+    // - \u{1F1FA}
+    // - \u{1F1F8}
     final List<TokenPosition> tokenPositions = [];
     int globalIndex = 0;