react-native-enriched-markdown-scaffold 1.0.2-scaffold.1 → 1.0.2-scaffold.10

package/ios/utils/ENRMChipDrawing.m

@@ -0,0 +1,83 @@
+#import "ENRMChipDrawing.h"
+
+static UIBezierPath *chipFillPath(CGRect rect, CGFloat r, BOOL isFirst, BOOL isLast)
+{
+#if !TARGET_OS_OSX
+  UIRectCorner corners = 0;
+  if (isFirst)
+    corners |= (UIRectCornerTopLeft | UIRectCornerBottomLeft);
+  if (isLast)
+    corners |= (UIRectCornerTopRight | UIRectCornerBottomRight);
+
+  return [UIBezierPath bezierPathWithRoundedRect:rect byRoundingCorners:corners cornerRadii:CGSizeMake(r, r)];
+#else
+  // NSBezierPath doesn't support per-corner rounding — use uniform corner radius
+  return UIBezierPathWithRoundedRect(rect, (isFirst || isLast) ? r : 0);
+#endif
+}
+
+static UIBezierPath *chipOpenBorderPath(CGRect rect, CGFloat r, CGFloat borderWidth, BOOL isFirst, BOOL isLast)
+{
+  UIBezierPath *path = [UIBezierPath bezierPath];
+  CGFloat inset = borderWidth / 2.0;
+  CGRect insetRect = CGRectInset(rect, inset, inset);
+
+  if (isFirst) {
+    [path moveToPoint:CGPointMake(CGRectGetMaxX(rect), insetRect.origin.y)];
+    BezierPathAddLine(path, CGPointMake(insetRect.origin.x + r, insetRect.origin.y));
+    BezierPathAddQuadCurve(path, CGPointMake(insetRect.origin.x, insetRect.origin.y + r),
+                           CGPointMake(insetRect.origin.x, insetRect.origin.y));
+    BezierPathAddLine(path, CGPointMake(insetRect.origin.x, CGRectGetMaxY(insetRect) - r));
+    BezierPathAddQuadCurve(path, CGPointMake(insetRect.origin.x + r, CGRectGetMaxY(insetRect)),
+                           CGPointMake(insetRect.origin.x, CGRectGetMaxY(insetRect)));
+    BezierPathAddLine(path, CGPointMake(CGRectGetMaxX(rect), CGRectGetMaxY(insetRect)));
+  } else if (isLast) {
+    [path moveToPoint:CGPointMake(rect.origin.x, insetRect.origin.y)];
+    BezierPathAddLine(path, CGPointMake(CGRectGetMaxX(insetRect) - r, insetRect.origin.y));
+    BezierPathAddQuadCurve(path, CGPointMake(CGRectGetMaxX(insetRect), insetRect.origin.y + r),
+                           CGPointMake(CGRectGetMaxX(insetRect), insetRect.origin.y));
+    BezierPathAddLine(path, CGPointMake(CGRectGetMaxX(insetRect), CGRectGetMaxY(insetRect) - r));
+    BezierPathAddQuadCurve(path, CGPointMake(CGRectGetMaxX(insetRect) - r, CGRectGetMaxY(insetRect)),
+                           CGPointMake(CGRectGetMaxX(insetRect), CGRectGetMaxY(insetRect)));
+    BezierPathAddLine(path, CGPointMake(rect.origin.x, CGRectGetMaxY(insetRect)));
+  } else {
+    [path moveToPoint:CGPointMake(rect.origin.x, insetRect.origin.y)];
+    BezierPathAddLine(path, CGPointMake(CGRectGetMaxX(rect), insetRect.origin.y));
+    [path moveToPoint:CGPointMake(rect.origin.x, CGRectGetMaxY(insetRect))];
+    BezierPathAddLine(path, CGPointMake(CGRectGetMaxX(rect), CGRectGetMaxY(insetRect)));
+  }
+  return path;
+}
+
+void ENRMDrawChipFragment(CGRect rect, RCTUIColor *backgroundColor, RCTUIColor *borderColor, CGFloat borderWidth,
+                          CGFloat cornerRadius, BOOL isFirst, BOOL isLast, BOOL strokeInset)
+{
+  if (CGRectIsEmpty(rect))
+    return;
+
+  CGFloat r = MIN(MAX(cornerRadius, 0), MIN(rect.size.width, rect.size.height) / 2.0);
+
+  if (backgroundColor) {
+    [backgroundColor setFill];
+    [chipFillPath(rect, r, isFirst, isLast) fill];
+  }
+
+  if (!borderColor || borderWidth <= 0)
+    return;
+
+  [borderColor setStroke];
+  UIBezierPath *strokePath;
+  if (isFirst && isLast) {
+    if (strokeInset) {
+      CGFloat inset = borderWidth / 2.0;
+      strokePath = chipFillPath(CGRectInset(rect, inset, inset), MAX(r - inset, 0), YES, YES);
+    } else {
+      strokePath = chipFillPath(rect, r, YES, YES);
+    }
+  } else {
+    strokePath = chipOpenBorderPath(rect, r, borderWidth, isFirst, isLast);
+  }
+  strokePath.lineWidth = borderWidth;
+  BezierPathSetRoundStyle(strokePath);
+  [strokePath stroke];
+}

package/ios/utils/ENRMLinkChip.h

@@ -0,0 +1,70 @@
+#pragma once
+#import "ENRMUIKit.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// Marks a link range that carries chip styling. The value is one
+/// `ENRMLinkChip` instance per link: instances compare by identity, so two
+/// adjacent links never coalesce into one attribute run (one chip).
+extern NSString *const ENRMLinkChipAttributeName;
+
+/// Marks the spacer characters `LinkRenderer` inserts at both outer edges of a
+/// link to reserve `paddingHorizontal` in the line. Spacers are layout-only:
+/// every text exit point (copy, markdown/HTML export, decoration text) strips
+/// them by this attribute — never by character, since U+00A0 can be content.
+extern NSString *const ENRMLinkSpacerAttributeName;
+
+@interface ENRMLinkChip : NSObject
+@property (nonatomic, strong, nullable) RCTUIColor *backgroundColor;
+@property (nonatomic, strong, nullable) RCTUIColor *borderColor;
+@property (nonatomic, assign) CGFloat borderWidth;
+@property (nonatomic, assign) CGFloat borderRadius;
+@property (nonatomic, assign) CGFloat paddingHorizontal;
+@property (nonatomic, assign) CGFloat paddingVertical;
+/// YES when the chip paints something (a background or a visible border).
+@property (nonatomic, readonly) BOOL isVisible;
+@end
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/// A spacer character (U+00A0) whose advance is exactly `width`.
+///
+/// U+00A0 is line-break class GL: a break is allowed before it after a space
+/// but never after it, and never before it after a non-space — so a leading
+/// spacer always travels with the link's first glyph and a trailing one with
+/// its last glyph (no orphaned padding at a wrap). It uses a 1pt system font
+/// so its own advance and line-height contribution are negligible whatever
+/// the link font (a custom font may lack U+00A0), and NSKern makes up the rest.
+NSAttributedString *ENRMLinkSpacerString(NSDictionary<NSAttributedStringKey, id> *baseAttributes, CGFloat width);
+
+/// `string` without link spacers (returns `string` itself when it has none).
+NSAttributedString *ENRMAttributedStringByRemovingLinkSpacers(NSAttributedString *string);
+
+/// Plain text of `range` without link spacers.
+NSString *ENRMPlainTextByRemovingLinkSpacers(NSAttributedString *string, NSRange range);
+
+/// Falls back to a plain `NSBackgroundColorAttributeName` for every chip
+/// background, for text drawn without `TextViewLayoutManager` (table cells,
+/// RTF export). Radius, border and vertical padding are not represented.
+void ENRMApplyLinkChipBackgroundsAsTextBackground(NSMutableAttributedString *string);
+
+/// Enumerates the chip rect of every laid-out line fragment of the link at
+/// `charRange`, in text-container coordinates. The rect spans the glyphs
+/// (spacers included, so it already covers `paddingHorizontal`) horizontally
+/// and the link font's ascender..descender ± `paddingVertical` vertically.
+void ENRMEnumerateLinkChipFragments(NSLayoutManager *layoutManager, NSTextContainer *textContainer, NSRange charRange,
+                                    ENRMLinkChip *_Nullable chip,
+                                    void (^block)(CGRect rect, BOOL isFirst, BOOL isLast));
+
+/// Draws the visible link chips intersecting `glyphsToShow`. Called from the
+/// layout manager's background pass, before glyphs are drawn.
+void ENRMDrawLinkChipsForGlyphRange(NSLayoutManager *layoutManager, NSTextContainer *textContainer,
+                                    NSRange glyphsToShow, CGPoint origin);
+
+#ifdef __cplusplus
+}
+#endif
+
+NS_ASSUME_NONNULL_END

package/ios/utils/ENRMLinkChip.m

@@ -0,0 +1,213 @@
+#import "ENRMLinkChip.h"
+#import "ENRMChipDrawing.h"
+#import <CoreText/CoreText.h>
+
+NSString *const ENRMLinkChipAttributeName = @"ENRMLinkChip";
+NSString *const ENRMLinkSpacerAttributeName = @"ENRMLinkSpacer";
+
+static const unichar kSpacerChar = 0x00A0;
+static const CGFloat kSpacerFontSize = 1.0;
+
+@implementation ENRMLinkChip
+
+- (BOOL)isVisible
+{
+  return self.backgroundColor != nil || (self.borderColor != nil && self.borderWidth > 0);
+}
+
+@end
+
+#pragma mark - Spacers
+
+static CGFloat spacerAdvance(UIFont *font)
+{
+  CTFontRef ctFont = (__bridge CTFontRef)font;
+  UniChar character = kSpacerChar;
+  CGGlyph glyph = 0;
+  if (!CTFontGetGlyphsForCharacters(ctFont, &character, &glyph, 1))
+    return 0;
+  CGSize advance = CGSizeZero;
+  CTFontGetAdvancesForGlyphs(ctFont, kCTFontOrientationHorizontal, &glyph, &advance, 1);
+  return advance.width;
+}
+
+NSAttributedString *ENRMLinkSpacerString(NSDictionary<NSAttributedStringKey, id> *baseAttributes, CGFloat width)
+{
+  static UIFont *spacerFont;
+  static CGFloat spacerFontAdvance;
+  static dispatch_once_t onceToken;
+  dispatch_once(&onceToken, ^{
+    spacerFont = [UIFont systemFontOfSize:kSpacerFontSize];
+    spacerFontAdvance = spacerAdvance(spacerFont);
+  });
+
+  NSMutableDictionary *attributes = [baseAttributes mutableCopy] ?: [NSMutableDictionary dictionary];
+  attributes[NSFontAttributeName] = spacerFont;
+  attributes[NSKernAttributeName] = @(width - spacerFontAdvance);
+  attributes[ENRMLinkSpacerAttributeName] = @YES;
+  // Padding is not text: keep decorations and attachments off it.
+  [attributes removeObjectForKey:NSUnderlineStyleAttributeName];
+  [attributes removeObjectForKey:NSStrikethroughStyleAttributeName];
+  [attributes removeObjectForKey:NSAttachmentAttributeName];
+
+  NSString *spacer = [NSString stringWithCharacters:&kSpacerChar length:1];
+  return [[NSAttributedString alloc] initWithString:spacer attributes:attributes];
+}
+
+NSAttributedString *ENRMAttributedStringByRemovingLinkSpacers(NSAttributedString *string)
+{
+  __block NSMutableAttributedString *stripped = nil;
+  [string enumerateAttribute:ENRMLinkSpacerAttributeName
+                     inRange:NSMakeRange(0, string.length)
+                     options:NSAttributedStringEnumerationReverse
+                  usingBlock:^(id value, NSRange range, BOOL *stop) {
+                    if (!value)
+                      return;
+                    if (!stripped)
+                      stripped = [string mutableCopy];
+                    [stripped deleteCharactersInRange:range];
+                  }];
+  return stripped ?: string;
+}
+
+NSString *ENRMPlainTextByRemovingLinkSpacers(NSAttributedString *string, NSRange range)
+{
+  if (range.location == NSNotFound || NSMaxRange(range) > string.length)
+    return @"";
+  return ENRMAttributedStringByRemovingLinkSpacers([string attributedSubstringFromRange:range]).string;
+}
+
+void ENRMApplyLinkChipBackgroundsAsTextBackground(NSMutableAttributedString *string)
+{
+  [string enumerateAttribute:ENRMLinkChipAttributeName
+                     inRange:NSMakeRange(0, string.length)
+                     options:0
+                  usingBlock:^(ENRMLinkChip *chip, NSRange range, BOOL *stop) {
+                    if (chip.backgroundColor) {
+                      [string addAttribute:NSBackgroundColorAttributeName value:chip.backgroundColor range:range];
+                    }
+                  }];
+}
+
+#pragma mark - Geometry
+
+/// The font of the first non-spacer character of `charRange` — the spacer's
+/// 1pt font must not drive the chip's height.
+static UIFont *_Nullable chipFontInRange(NSTextStorage *storage, NSRange charRange)
+{
+  __block UIFont *font = nil;
+  [storage enumerateAttributesInRange:charRange
+                              options:0
+                           usingBlock:^(NSDictionary<NSAttributedStringKey, id> *attrs, NSRange range, BOOL *stop) {
+                             if (attrs[ENRMLinkSpacerAttributeName])
+                               return;
+                             font = attrs[NSFontAttributeName];
+                             *stop = font != nil;
+                           }];
+  return font;
+}
+
+void ENRMEnumerateLinkChipFragments(NSLayoutManager *layoutManager, NSTextContainer *textContainer, NSRange charRange,
+                                    ENRMLinkChip *chip, void (^block)(CGRect rect, BOOL isFirst, BOOL isLast))
+{
+  NSTextStorage *storage = layoutManager.textStorage;
+  if (charRange.length == 0 || NSMaxRange(charRange) > storage.length)
+    return;
+
+  NSRange glyphRange = [layoutManager glyphRangeForCharacterRange:charRange actualCharacterRange:NULL];
+  if (glyphRange.location == NSNotFound || glyphRange.length == 0)
+    return;
+
+  CGFloat paddingHorizontal = chip.paddingHorizontal;
+  CGFloat paddingVertical = chip.paddingVertical;
+
+  [layoutManager
+      enumerateLineFragmentsForGlyphRange:glyphRange
+                               usingBlock:^(CGRect lineRect, CGRect usedRect, NSTextContainer *tc, NSRange lineRange,
+                                            BOOL *stop) {
+                                 NSRange intersect = NSIntersectionRange(lineRange, glyphRange);
+                                 if (intersect.length == 0)
+                                   return;
+
+                                 BOOL isFirst = intersect.location == glyphRange.location;
+                                 BOOL isLast = NSMaxRange(intersect) == NSMaxRange(glyphRange);
+
+                                 CGRect textRect = [layoutManager boundingRectForGlyphRange:intersect
+                                                                            inTextContainer:textContainer];
+                                 NSRange fragmentChars = [layoutManager characterRangeForGlyphRange:intersect
+                                                                                   actualGlyphRange:NULL];
+                                 NSUInteger lineEnd = NSMaxRange(lineRange);
+                                 CGFloat left =
+                                     lineRect.origin.x + [layoutManager locationForGlyphAtIndex:intersect.location].x;
+
+                                 NSUInteger visibleCharEnd = NSMaxRange(fragmentChars);
+                                 NSString *chars = storage.string;
+                                 NSCharacterSet *breakable = [NSCharacterSet whitespaceAndNewlineCharacterSet];
+                                 while (visibleCharEnd > fragmentChars.location &&
+                                        [chars characterAtIndex:visibleCharEnd - 1] != kSpacerChar &&
+                                        [breakable characterIsMember:[chars characterAtIndex:visibleCharEnd - 1]]) {
+                                   visibleCharEnd--;
+                                 }
+                                 NSUInteger visibleGlyphEnd = NSMaxRange(intersect);
+                                 if (visibleCharEnd < NSMaxRange(fragmentChars)) {
+                                   visibleGlyphEnd = [layoutManager glyphIndexForCharacterAtIndex:visibleCharEnd];
+                                 }
+
+                                 CGFloat right;
+                                 if (visibleGlyphEnd < lineEnd) {
+                                   right =
+                                       lineRect.origin.x + [layoutManager locationForGlyphAtIndex:visibleGlyphEnd].x;
+                                 } else {
+                                   right = CGRectGetMaxX(usedRect);
+                                 }
+                                 if (isLast && paddingHorizontal > 0) {
+                                   NSUInteger lastGlyph = NSMaxRange(intersect) - 1;
+                                   CGFloat spacerX =
+                                       lineRect.origin.x + [layoutManager locationForGlyphAtIndex:lastGlyph].x;
+                                   right = MAX(right, spacerX + paddingHorizontal);
+                                 }
+
+                                 UIFont *font = chipFontInRange(storage, fragmentChars);
+                                 CGFloat top = CGRectGetMinY(textRect);
+                                 CGFloat bottom = CGRectGetMaxY(textRect);
+                                 if (font) {
+                                   // locationForGlyphAtIndex: y is the baseline within the line fragment.
+                                   CGFloat baseline =
+                                       lineRect.origin.y + [layoutManager locationForGlyphAtIndex:intersect.location].y;
+                                   top = baseline - font.ascender;
+                                   bottom = baseline - font.descender;
+                                 }
+                                 top -= paddingVertical;
+                                 bottom += paddingVertical;
+
+                                 block(CGRectMake(left, top, right - left, bottom - top), isFirst, isLast);
+                               }];
+}
+
+#pragma mark - Drawing
+
+void ENRMDrawLinkChipsForGlyphRange(NSLayoutManager *layoutManager, NSTextContainer *textContainer,
+                                    NSRange glyphsToShow, CGPoint origin)
+{
+  NSTextStorage *storage = layoutManager.textStorage;
+  NSRange charRange = [layoutManager characterRangeForGlyphRange:glyphsToShow actualGlyphRange:NULL];
+  if (charRange.location == NSNotFound || charRange.length == 0)
+    return;
+
+  // Enumerate the whole storage (like CodeBackground) so a chip that starts
+  // before the dirty range still gets its full rect.
+  [storage
+      enumerateAttribute:ENRMLinkChipAttributeName
+                 inRange:NSMakeRange(0, storage.length)
+                 options:0
+              usingBlock:^(ENRMLinkChip *chip, NSRange range, BOOL *stop) {
+                if (!chip.isVisible || NSIntersectionRange(range, charRange).length == 0)
+                  return;
+
+                ENRMEnumerateLinkChipFragments(
+                    layoutManager, textContainer, range, chip, ^(CGRect rect, BOOL isFirst, BOOL isLast) {
+                      ENRMDrawChipFragment(CGRectOffset(rect, origin.x, origin.y), chip.backgroundColor,
+                                           chip.borderColor, chip.borderWidth, chip.borderRadius, isFirst, isLast, YES);
+                    });
+              }];
+}

package/ios/utils/ENRMLinkLayout.h

@@ -0,0 +1,50 @@
+#pragma once
+#import "ENRMUIKit.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/// Collects the chip rect of every link fragment laid out in `textView`, for
+/// the `onLinkLayout` event. Each entry is
+/// `@{linkIndex, url, text, x, y, width, height}` (NSNumber/NSString), so a
+/// payload compares with `-isEqualToArray:` for deduplication.
+///
+/// - `offset` is added to every rect (a segment's origin inside its container).
+/// - Links are numbered in document order starting at `indexBase`; the number
+///   of links found is written to `outLinkCount` so the next segment continues.
+///
+/// Rects are in points relative to the text view, which the markdown views
+/// configure with zero insets and no line-fragment padding.
+NSArray<NSDictionary *> *ENRMCollectLinkLayoutFragments(ENRMPlatformTextView *textView, CGPoint offset,
+                                                        NSInteger indexBase, NSInteger *_Nullable outLinkCount);
+
+#ifdef __cplusplus
+}
+#endif
+
+#ifdef __cplusplus
+/// Converts collected fragments into a codegen `OnLinkLayout` payload. Templated
+/// because each component has its own (structurally identical) event struct.
+template <typename Event> inline Event ENRMLinkLayoutEventFromFragments(NSArray<NSDictionary *> *fragments)
+{
+  Event event;
+  event.fragments.reserve(fragments.count);
+  for (NSDictionary *fragment in fragments) {
+    typename decltype(event.fragments)::value_type item;
+    item.linkIndex = [fragment[@"linkIndex"] intValue];
+    item.url = std::string([fragment[@"url"] UTF8String] ?: "");
+    item.text = std::string([fragment[@"text"] UTF8String] ?: "");
+    item.x = [fragment[@"x"] doubleValue];
+    item.y = [fragment[@"y"] doubleValue];
+    item.width = [fragment[@"width"] doubleValue];
+    item.height = [fragment[@"height"] doubleValue];
+    event.fragments.push_back(item);
+  }
+  return event;
+}
+#endif
+
+NS_ASSUME_NONNULL_END

package/ios/utils/ENRMLinkLayout.m

@@ -0,0 +1,45 @@
+#import "ENRMLinkLayout.h"
+#import "ENRMLinkChip.h"
+
+NSArray<NSDictionary *> *ENRMCollectLinkLayoutFragments(ENRMPlatformTextView *textView, CGPoint offset,
+                                                        NSInteger indexBase, NSInteger *outLinkCount)
+{
+  NSLayoutManager *layoutManager = textView.layoutManager;
+  NSTextContainer *textContainer = textView.textContainer;
+  NSTextStorage *storage = layoutManager.textStorage;
+  NSMutableArray<NSDictionary *> *fragments = [NSMutableArray array];
+  __block NSInteger linkIndex = indexBase;
+
+  if (storage.length > 0 && textContainer != nil) {
+    // LinkRenderer attaches one ENRMLinkChip instance per link, so each
+    // attribute run is exactly one link (adjacent links never coalesce).
+    [storage enumerateAttribute:ENRMLinkChipAttributeName
+                        inRange:NSMakeRange(0, storage.length)
+                        options:0
+                     usingBlock:^(ENRMLinkChip *chip, NSRange range, BOOL *stop) {
+                       if (!chip)
+                         return;
+                       id link = [storage attribute:NSLinkAttributeName atIndex:range.location effectiveRange:NULL];
+                       NSString *url = [link isKindOfClass:[NSURL class]] ? [(NSURL *)link absoluteString] : link;
+                       NSString *text = ENRMPlainTextByRemovingLinkSpacers(storage, range);
+                       NSNumber *index = @(linkIndex++);
+
+                       ENRMEnumerateLinkChipFragments(layoutManager, textContainer, range, chip,
+                                                      ^(CGRect rect, BOOL isFirst, BOOL isLast) {
+                                                        [fragments addObject:@{
+                                                          @"linkIndex" : index,
+                                                          @"url" : url ?: @"",
+                                                          @"text" : text,
+                                                          @"x" : @(rect.origin.x + offset.x),
+                                                          @"y" : @(rect.origin.y + offset.y),
+                                                          @"width" : @(rect.size.width),
+                                                          @"height" : @(rect.size.height),
+                                                        }];
+                                                      });
+                     }];
+  }
+
+  if (outLinkCount)
+    *outLinkCount = linkIndex - indexBase;
+  return fragments;
+}

package/ios/utils/ENRMSelectionChange.h

@@ -0,0 +1,120 @@
+#pragma once
+#import "ENRMUIKit.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// Keys of an `onSelectionChange` payload. Rects are `NSValue`-wrapped CGRects in
+/// the reporting view's coordinates, so a payload compares with `-isEqual:` for
+/// deduplication.
+extern NSString *const ENRMSelectionActiveKey;
+extern NSString *const ENRMSelectionSourceKey;
+extern NSString *const ENRMSelectionTextKey;
+extern NSString *const ENRMSelectionMarkdownKey;
+extern NSString *const ENRMSelectionWholeKey;
+extern NSString *const ENRMSelectionRectKey;
+extern NSString *const ENRMSelectionStartRectKey;
+extern NSString *const ENRMSelectionEndRectKey;
+extern NSString *const ENRMSelectionAdjustingKey;
+/// Only in `ENRMTextSelectionInTextView` results: whether the range spans the
+/// whole text (same threshold `markdownForRange` uses for the cached markdown).
+extern NSString *const ENRMSelectionFullKey;
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/// The payload reported once the selection is gone.
+NSDictionary *ENRMInactiveSelectionPayload(void);
+
+/// A long-pressed block (table / math / code): `whole`, every rect is `frame`.
+NSDictionary *ENRMBlockSelectionPayload(NSString *source, NSString *markdown, NSString *text, CGRect frame);
+
+#if !TARGET_OS_OSX
+/// Text, full-selection flag and rects of `textView`'s selection, converted to
+/// `targetView`'s coordinates; nil when nothing is selected. `rect` is the union
+/// of the selection rects, `startRect` / `endRect` the rects holding its start
+/// and end. The owner adds source, markdown and whole to build the payload.
+NSDictionary *_Nullable ENRMTextSelectionInTextView(UITextView *textView, UIView *targetView);
+#endif
+
+#ifdef __cplusplus
+}
+#endif
+
+/// Coalesces selection changes into at most one report per run loop turn. The
+/// payload is read when the turn fires, so the latest state always reaches JS;
+/// a cleared selection is reported right away and drops any pending update.
+/// Identical payloads are sent once.
+@interface ENRMSelectionChangeReporter : NSObject
+
+- (instancetype)initWithSnapshot:(NSDictionary * (^)(void))snapshot
+                            emit:(void (^)(NSDictionary *payload))emit NS_DESIGNATED_INITIALIZER;
+- (instancetype)init NS_UNAVAILABLE;
+
+/// Off by default. Toggling resets the last reported payload to inactive.
+@property (nonatomic, assign) BOOL enabled;
+
+- (void)schedule;
+- (void)selectionChanged:(BOOL)hasSelection;
+- (void)flushNow;
+- (void)cancel;
+/// Makes the next report go out even if it equals the last one — a block
+/// long-pressed again is a new request for the app's menu, not a repeat.
+- (void)forgetLastReported;
+
+@end
+
+#if !TARGET_OS_OSX
+/// Tells when the user is dragging a selection handle (or holding the loupe).
+/// `UITextView` doesn't call `textViewDidChangeSelection:` during the drag, so
+/// this watches the text view's own selection gestures: every recognizer of
+/// the view and its subviews except scroll, pinch and taps. UIKit adds the
+/// handle recognizers lazily, so call `trackTextView:` again on each selection
+/// change. `change` runs whenever `adjusting` flips.
+@interface ENRMSelectionGestureTracker : NSObject
+
+- (instancetype)initWithChange:(void (^)(void))change NS_DESIGNATED_INITIALIZER;
+- (instancetype)init NS_UNAVAILABLE;
+
+/// A tracked gesture is in `Began` / `Changed`.
+@property (nonatomic, readonly) BOOL adjusting;
+
+- (void)trackTextView:(UITextView *)textView;
+/// Clears `adjusting` without calling `change` (view recycling).
+- (void)reset;
+
+@end
+#endif
+
+#ifdef __cplusplus
+/// Converts a payload into a codegen `OnSelectionChange` struct. Templated
+/// because each component has its own (structurally identical) event struct.
+template <typename Event> inline Event ENRMSelectionChangeEventFromPayload(NSDictionary *payload)
+{
+  Event event;
+  event.active = [payload[ENRMSelectionActiveKey] boolValue];
+  event.source = std::string([payload[ENRMSelectionSourceKey] UTF8String] ?: "selection");
+  event.text = std::string([payload[ENRMSelectionTextKey] UTF8String] ?: "");
+  event.markdown = std::string([payload[ENRMSelectionMarkdownKey] UTF8String] ?: "");
+  event.whole = [payload[ENRMSelectionWholeKey] boolValue];
+  event.adjusting = [payload[ENRMSelectionAdjustingKey] boolValue];
+
+  auto assign = [](auto &target, NSValue *value) {
+#if TARGET_OS_OSX
+    CGRect rect = value ? NSRectToCGRect(value.rectValue) : CGRectZero;
+#else
+    CGRect rect = value ? value.CGRectValue : CGRectZero;
+#endif
+    target.x = rect.origin.x;
+    target.y = rect.origin.y;
+    target.width = rect.size.width;
+    target.height = rect.size.height;
+  };
+  assign(event.rect, payload[ENRMSelectionRectKey]);
+  assign(event.startRect, payload[ENRMSelectionStartRectKey]);
+  assign(event.endRect, payload[ENRMSelectionEndRectKey]);
+  return event;
+}
+#endif
+
+NS_ASSUME_NONNULL_END