@mathers101/react-native-render-rich-text 0.0.0-stage → 0.1.9

package/ios/utils/CodeBlockBackground.m

@@ -0,0 +1,103 @@
+#import "CodeBlockBackground.h"
+#import "ENRMUIKit.h"
+#import "LastElementUtils.h"
+#import "StyleConfig.h"
+
+// Draws the commonmark-flavor code block box behind the text view's glyph
+// runs. The visual conventions (half-stroke border inset, corner radius
+// handling) must stay in sync with the whole-rect box the github flavor
+// draws in ENRMCodeBlockContainerView's drawRect:.
+
+@implementation CodeBlockBackground {
+  StyleConfig *_config;
+}
+
+- (instancetype)initWithConfig:(StyleConfig *)config
+{
+  if (self = [super init]) {
+    _config = config;
+  }
+  return self;
+}
+
+- (void)drawBackgroundsForGlyphRange:(NSRange)glyphsToShow
+                       layoutManager:(NSLayoutManager *)layoutManager
+                       textContainer:(NSTextContainer *)textContainer
+                             atPoint:(CGPoint)origin
+{
+  NSTextStorage *textStorage = layoutManager.textStorage;
+  NSRange charRange = [layoutManager characterRangeForGlyphRange:glyphsToShow actualGlyphRange:NULL];
+
+  // Enumerate over the full storage range so each code block's full rect is drawn.
+  // Restricting to charRange causes partial rects per draw pass, which produces
+  // multiple stacked oval shapes when border radius is large.
+  // The graphics context clip ensures only the visible portion is painted.
+  [textStorage enumerateAttribute:CodeBlockAttributeName
+                          inRange:NSMakeRange(0, textStorage.length)
+                          options:0
+                       usingBlock:^(id value, NSRange range, BOOL *stop) {
+                         if (!value)
+                           return;
+                         if (NSIntersectionRange(range, charRange).length == 0)
+                           return;
+                         [self drawCodeBlockBackgroundForRange:range
+                                                 layoutManager:layoutManager
+                                                 textContainer:textContainer
+                                                       atPoint:origin];
+                       }];
+}
+
+- (void)drawCodeBlockBackgroundForRange:(NSRange)range
+                          layoutManager:(NSLayoutManager *)layoutManager
+                          textContainer:(NSTextContainer *)textContainer
+                                atPoint:(CGPoint)origin
+{
+  NSRange glyphRange = [layoutManager glyphRangeForCharacterRange:range actualCharacterRange:NULL];
+  CGRect blockRect = [layoutManager boundingRectForGlyphRange:glyphRange inTextContainer:textContainer];
+
+  if (CGRectIsEmpty(blockRect))
+    return;
+
+  NSNumber *indentAttr = [layoutManager.textStorage attribute:CodeBlockIndentAttributeName
+                                                      atIndex:range.location
+                                               effectiveRange:NULL];
+  CGFloat indent = [indentAttr doubleValue];
+
+  CGFloat availableWidth = textContainer.size.width - indent;
+  if (availableWidth <= 0)
+    return;
+
+  blockRect.origin.x = origin.x + indent;
+  blockRect.origin.y += origin.y;
+  blockRect.size.width = availableWidth;
+
+  // We extend the background specifically to cover the bottom padding spacer,
+  // excluding any additional marginBottom applied via measurement.
+  BOOL isLastCodeBlock = (NSMaxRange(range) == layoutManager.textStorage.length);
+  if (isLastCodeBlock) {
+    blockRect.size.height += [_config codeBlockPadding];
+  }
+
+  CGFloat borderWidth = [_config codeBlockBorderWidth];
+  CGFloat borderRadius = [_config codeBlockBorderRadius];
+  CGFloat inset = borderWidth / 2.0;
+
+  CGRect insetRect = CGRectInset(blockRect, inset, inset);
+  UIBezierPath *path = UIBezierPathWithRoundedRect(insetRect, MAX(0, borderRadius - inset));
+
+  CGContextRef ctx = UIGraphicsGetCurrentContext();
+  CGContextSaveGState(ctx);
+  {
+    [[_config codeBlockBackgroundColor] setFill];
+    [path fill];
+
+    if (borderWidth > 0) {
+      [[_config codeBlockBorderColor] setStroke];
+      path.lineWidth = borderWidth;
+      BezierPathSetRoundStyle(path);
+      [path stroke];
+    }
+  }
+  CGContextRestoreGState(ctx);
+}
+@end

package/ios/utils/ContextMenuUtils.h

@@ -0,0 +1,76 @@
+#pragma once
+
+#import "ENRMUIKit.h"
+#import <Foundation/Foundation.h>
+
+#ifdef __cplusplus
+#include <string>
+#include <vector>
+
+template <typename T>
+static bool ENRMContextMenuItemsChanged(const std::vector<T> &oldItems, const std::vector<T> &newItems)
+{
+  if (newItems.size() != oldItems.size()) {
+    return true;
+  }
+  for (size_t i = 0; i < newItems.size(); i++) {
+    if (newItems[i].text != oldItems[i].text || newItems[i].icon != oldItems[i].icon) {
+      return true;
+    }
+  }
+  return false;
+}
+
+template <typename T> static NSArray<NSString *> *ENRMContextMenuTextsFromItems(const std::vector<T> &items)
+{
+  NSMutableArray<NSString *> *result = [NSMutableArray new];
+  for (const auto &item : items) {
+    [result addObject:[NSString stringWithUTF8String:item.text.c_str()]];
+  }
+  return [result copy];
+}
+
+template <typename T> static NSArray<NSString *> *_Nullable ENRMContextMenuIconsFromItems(const std::vector<T> &items)
+{
+  NSMutableArray<NSString *> *result = [NSMutableArray arrayWithCapacity:items.size()];
+  bool hasAnyIcon = false;
+  for (const auto &item : items) {
+    NSString *iconName = @(item.icon.c_str());
+    hasAnyIcon = hasAnyIcon || iconName.length > 0;
+    [result addObject:iconName];
+  }
+  return hasAnyIcon ? [result copy] : nil;
+}
+
+#endif
+
+typedef void (^ENRMContextMenuPressHandler)(NSString *_Nonnull itemText, NSString *_Nonnull selectedText,
+                                            NSUInteger selectionStart, NSUInteger selectionEnd);
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#if !TARGET_OS_OSX
+
+// TODO: Remove API_AVAILABLE(ios(16.0)) guard when the minimum iOS deployment target in RN is bumped to 16.
+NSMutableArray<UIAction *> *_Nullable ENRMBuildContextMenuActions(NSArray<NSString *> *_Nonnull itemTexts,
+                                                                  NSArray<NSString *> *_Nullable iconNames,
+                                                                  UITextView *_Nonnull textView, NSRange selectedRange,
+                                                                  ENRMContextMenuPressHandler _Nonnull handler)
+    API_AVAILABLE(ios(16.0));
+
+#else
+
+NSArray<NSMenuItem *> *_Nullable ENRMBuildContextMenuItems(NSArray<NSString *> *_Nonnull itemTexts,
+                                                           NSArray<NSString *> *_Nullable iconNames,
+                                                           NSTextView *_Nonnull textView,
+                                                           ENRMContextMenuPressHandler _Nonnull handler);
+
+void ENRMPrependMenuItems(NSMenu *_Nonnull menu, NSArray<NSMenuItem *> *_Nullable items);
+
+#endif
+
+#ifdef __cplusplus
+}
+#endif

package/ios/utils/ContextMenuUtils.mm

@@ -0,0 +1,75 @@
+#import "ContextMenuUtils.h"
+#import "ENRMLinkPillText.h"
+#import "ENRMMenuAction.h"
+
+#if !TARGET_OS_OSX
+
+// TODO: Remove API_AVAILABLE(ios(16.0)) guard when the minimum iOS deployment target in RN is bumped to 16.
+NSMutableArray<UIAction *> *_Nullable ENRMBuildContextMenuActions(NSArray<NSString *> *itemTexts,
+                                                                  NSArray<NSString *> *_Nullable iconNames,
+                                                                  UITextView *textView, NSRange selectedRange,
+                                                                  ENRMContextMenuPressHandler handler)
+    API_AVAILABLE(ios(16.0))
+{
+  if (itemTexts.count == 0) {
+    return nil;
+  }
+
+  NSString *selectedText =
+      ENRMStringByExpandingLinkPills([textView.textStorage attributedSubstringFromRange:selectedRange]);
+  NSUInteger selectionStart = selectedRange.location;
+  NSUInteger selectionEnd = NSMaxRange(selectedRange);
+
+  NSMutableArray<UIAction *> *actions = [NSMutableArray arrayWithCapacity:itemTexts.count];
+  [itemTexts enumerateObjectsUsingBlock:^(NSString *itemText, NSUInteger index, BOOL *_) {
+    NSString *iconName = iconNames ? iconNames[index] : nil;
+    UIImage *image = iconName.length > 0 ? [UIImage systemImageNamed:iconName] : nil;
+    [actions addObject:[UIAction actionWithTitle:itemText
+                                           image:image
+                                      identifier:nil
+                                         handler:^(__kindof UIAction *_) {
+                                           handler(itemText, selectedText, selectionStart, selectionEnd);
+                                         }]];
+  }];
+  return actions;
+}
+
+#else
+
+NSArray<NSMenuItem *> *_Nullable ENRMBuildContextMenuItems(NSArray<NSString *> *itemTexts,
+                                                           NSArray<NSString *> *_Nullable iconNames,
+                                                           NSTextView *textView, ENRMContextMenuPressHandler handler)
+{
+  if (itemTexts.count == 0) {
+    return nil;
+  }
+
+  NSRange selectedRange = textView.selectedRange;
+  NSString *selectedText = [textView.string substringWithRange:selectedRange];
+  NSUInteger selectionStart = selectedRange.location;
+  NSUInteger selectionEnd = NSMaxRange(selectedRange);
+
+  NSMutableArray<NSMenuItem *> *items = [NSMutableArray arrayWithCapacity:itemTexts.count];
+  [itemTexts enumerateObjectsUsingBlock:^(NSString *itemText, NSUInteger index, BOOL *_) {
+    NSMenuItem *item =
+        ENRMCreateMenuItem(itemText, ^{ handler(itemText, selectedText, selectionStart, selectionEnd); });
+    NSString *iconName = iconNames ? iconNames[index] : nil;
+    if (iconName.length > 0) {
+      item.image = [NSImage imageWithSystemSymbolName:iconName accessibilityDescription:nil];
+    }
+    [items addObject:item];
+  }];
+  return items;
+}
+
+void ENRMPrependMenuItems(NSMenu *menu, NSArray<NSMenuItem *> *items)
+{
+  if (items.count == 0) {
+    return;
+  }
+  [menu insertItem:[NSMenuItem separatorItem] atIndex:0];
+  [items enumerateObjectsWithOptions:NSEnumerationReverse
+                          usingBlock:^(NSMenuItem *item, NSUInteger _, BOOL *__) { [menu insertItem:item atIndex:0]; }];
+}
+
+#endif

package/ios/utils/ENRMAccessibilityLabels.h

@@ -0,0 +1,40 @@
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface ENRMAccessibilityLabels : NSObject
+
+@property (nonatomic, copy) NSString *bulletPoint;
+@property (nonatomic, copy) NSString *nestedBulletPoint;
+@property (nonatomic, copy) NSString *orderedItem;
+@property (nonatomic, copy) NSString *nestedOrderedItem;
+@property (nonatomic, copy) NSString *blockquote;
+@property (nonatomic, copy) NSString *nestedBlockquote;
+@property (nonatomic, copy) NSString *tableRow;
+@property (nonatomic, copy) NSString *mathEquation;
+@property (nonatomic, copy) NSString *codeBlockWrap;
+@property (nonatomic, copy) NSString *codeBlockUnwrap;
+@property (nonatomic, copy) NSString *rotorHeadings;
+@property (nonatomic, copy) NSString *rotorLinks;
+@property (nonatomic, copy) NSString *rotorImages;
+
+@end
+
+NS_ASSUME_NONNULL_END
+
+#ifdef __cplusplus
+template <typename T> static bool ENRMAccessibilityLabelsChanged(const T &oldLabels, const T &newLabels)
+{
+  return oldLabels.list.bulletPoint != newLabels.list.bulletPoint ||
+         oldLabels.list.nestedBulletPoint != newLabels.list.nestedBulletPoint ||
+         oldLabels.list.orderedItem != newLabels.list.orderedItem ||
+         oldLabels.list.nestedOrderedItem != newLabels.list.nestedOrderedItem ||
+         oldLabels.blockquote.quote != newLabels.blockquote.quote ||
+         oldLabels.blockquote.nestedQuote != newLabels.blockquote.nestedQuote ||
+         oldLabels.table.row != newLabels.table.row || oldLabels.math.equation != newLabels.math.equation ||
+         oldLabels.codeBlock.wrap != newLabels.codeBlock.wrap ||
+         oldLabels.codeBlock.unwrap != newLabels.codeBlock.unwrap ||
+         oldLabels.rotor.headings != newLabels.rotor.headings || oldLabels.rotor.links != newLabels.rotor.links ||
+         oldLabels.rotor.images != newLabels.rotor.images;
+}
+#endif

package/ios/utils/ENRMAccessibilityLabels.m

@@ -0,0 +1,5 @@
+#import "ENRMAccessibilityLabels.h"
+
+@implementation ENRMAccessibilityLabels
+
+@end

package/ios/utils/ENRMAsyncRenderCoordinator.h

@@ -0,0 +1,24 @@
+#pragma once
+#import <Foundation/Foundation.h>
+
+/// Owns the serial render queue and render-ID counter used by async render pipelines.
+/// Handles stale-result cancellation and main-thread dispatch automatically.
+/// Set blockAsyncRender = YES before synchronous rendering to suppress queued dispatches.
+@interface ENRMAsyncRenderCoordinator : NSObject
+
+@property (nonatomic) BOOL blockAsyncRender;
+
+- (instancetype)initWithQueueLabel:(const char *)label NS_DESIGNATED_INITIALIZER;
+- (instancetype)init NS_UNAVAILABLE;
+
+/// Dispatches renderBlock on the serial queue.
+/// If renderBlock returns YES, applyBlock is dispatched on the main queue,
+/// provided the render ID has not been superseded by a newer call.
+- (void)scheduleRender:(BOOL (^)(void))renderBlock apply:(dispatch_block_t)applyBlock;
+
+/// Advances the render ID so any in-flight render's apply block is discarded
+/// by the renderId == currentRenderId check when it lands on the main queue.
+/// Use before recycling or otherwise resetting a host that owns this coordinator.
+- (void)invalidate;
+
+@end

package/ios/utils/ENRMAsyncRenderCoordinator.m

@@ -0,0 +1,37 @@
+#import "ENRMAsyncRenderCoordinator.h"
+
+@implementation ENRMAsyncRenderCoordinator {
+  dispatch_queue_t _queue;
+  NSUInteger _currentRenderId;
+}
+
+- (instancetype)initWithQueueLabel:(const char *)label
+{
+  if (self = [super init]) {
+    _queue = dispatch_queue_create(label, DISPATCH_QUEUE_SERIAL);
+  }
+  return self;
+}
+
+- (void)scheduleRender:(BOOL (^)(void))renderBlock apply:(dispatch_block_t)applyBlock
+{
+  if (_blockAsyncRender)
+    return;
+  NSUInteger renderId = ++_currentRenderId;
+  dispatch_async(_queue, ^{
+    if (!renderBlock())
+      return;
+    dispatch_async(dispatch_get_main_queue(), ^{
+      if (renderId == self->_currentRenderId) {
+        applyBlock();
+      }
+    });
+  });
+}
+
+- (void)invalidate
+{
+  ++_currentRenderId;
+}
+
+@end

package/ios/utils/ENRMAtomicSize.h

@@ -0,0 +1,65 @@
+#pragma once
+
+#include <CoreGraphics/CGGeometry.h>
+#include <atomic>
+#include <cstdint>
+#include <cstring>
+
+/**
+ * Lock-free size mailbox (issue #550).
+ *
+ * `measureContent` may run on the JS/layout thread while React Native holds
+ * the ShadowTree revision mutex (`preventShadowTreeCommitExhaustion` re-runs
+ * the entire commit — layout included — under `revisionMutexRecursive_` after
+ * three failed optimistic commits). A main-thread committer (e.g. Reanimated)
+ * can already be blocked on that same mutex, so any `dispatch_sync` to main
+ * from the measure path can deadlock: JS waits for main, main waits for the
+ * mutex JS holds. iOS kills the frozen app ~60s later (watchdog 0x8BADF00D).
+ *
+ * Reading `view.bounds` from a background thread is not safe either, so the
+ * component view *publishes* its last committed size here (from
+ * `updateLayoutMetrics:`, always on main) and the measure path *loads* it
+ * wait-free from any thread.
+ *
+ * Both dimensions are packed as IEEE-754 floats into one `uint64_t` so a
+ * single lock-free atomic covers the pair — a reader can never observe a new
+ * width with an old height (no torn reads). Relaxed memory ordering suffices:
+ * the value is self-contained and no other memory is published through it.
+ */
+class ENRMAtomicSize {
+public:
+  void store(CGSize size)
+  {
+    bits_.store(pack(size), std::memory_order_relaxed);
+  }
+
+  CGSize load() const
+  {
+    return unpack(bits_.load(std::memory_order_relaxed));
+  }
+
+private:
+  static uint64_t pack(CGSize size)
+  {
+    float width = (float)size.width;
+    float height = (float)size.height;
+    uint32_t widthBits;
+    uint32_t heightBits;
+    memcpy(&widthBits, &width, sizeof(widthBits));
+    memcpy(&heightBits, &height, sizeof(heightBits));
+    return ((uint64_t)widthBits << 32) | heightBits;
+  }
+
+  static CGSize unpack(uint64_t bits)
+  {
+    uint32_t widthBits = (uint32_t)(bits >> 32);
+    uint32_t heightBits = (uint32_t)bits;
+    float width;
+    float height;
+    memcpy(&width, &widthBits, sizeof(width));
+    memcpy(&height, &heightBits, sizeof(height));
+    return CGSizeMake(width, height);
+  }
+
+  std::atomic<uint64_t> bits_{0};
+};

package/ios/utils/ENRMCodeBlockContent.h

@@ -0,0 +1,37 @@
+#pragma once
+
+#import <Foundation/Foundation.h>
+
+@class TiptapASTNode;
+@class StyleConfig;
+
+NS_ASSUME_NONNULL_BEGIN
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/// Shared code block node semantics, used by both tiptap flavors so the
+/// meaning of a CodeBlock AST node (its text, language, fence) is defined in
+/// one place. Language display names come from the shared C++ core
+/// (cpp/highlight/CodeBlockLanguages.hpp) so all platforms label fences
+/// identically.
+
+NSString *ENRMCodeBlockExtractCode(TiptapASTNode *node);
+NSString *_Nullable ENRMCodeBlockLanguage(TiptapASTNode *node);
+NSString *ENRMCodeBlockFenceChar(TiptapASTNode *node);
+NSString *ENRMCodeBlockFencedTiptap(NSString *code, NSString *_Nullable language, NSString *fenceChar);
+NSString *ENRMCodeBlockDisplayLanguageName(NSString *_Nullable language);
+
+/// Applies the flavor-independent code block text attributes (code font,
+/// color, line height, forced-LTR left-aligned paragraph) to the range.
+/// Callers layer their container-specific paragraph adjustments on top (the
+/// commonmark span flavor adds padding indents; the github block view has
+/// none).
+void ENRMApplyCodeBlockTextAttributes(NSMutableAttributedString *string, NSRange range, StyleConfig *config);
+
+#ifdef __cplusplus
+}
+#endif
+
+NS_ASSUME_NONNULL_END

package/ios/utils/ENRMCodeBlockContent.mm

@@ -0,0 +1,89 @@
+#import "ENRMCodeBlockContent.h"
+#import "ENRMUIKit.h"
+#import "TiptapASTNode.h"
+#import "ParagraphStyleUtils.h"
+#import "StyleConfig.h"
+
+static void ENRMAppendNodeContent(TiptapASTNode *node, NSMutableString *output)
+{
+  if (node.content.length > 0) {
+    [output appendString:node.content];
+  }
+  for (TiptapASTNode *child in node.children) {
+    ENRMAppendNodeContent(child, output);
+  }
+}
+
+NSString *ENRMCodeBlockExtractCode(TiptapASTNode *node)
+{
+  NSMutableString *code = [NSMutableString string];
+  ENRMAppendNodeContent(node, code);
+  NSUInteger end = code.length;
+  while (end > 0 && [code characterAtIndex:end - 1] == '\n') {
+    end--;
+  }
+  return [code substringToIndex:end];
+}
+
+NSString *ENRMCodeBlockLanguage(TiptapASTNode *node)
+{
+  NSString *language = node.attributes[@"language"];
+  return language.length > 0 ? language : nil;
+}
+
+NSString *ENRMCodeBlockFenceChar(TiptapASTNode *node)
+{
+  NSString *fenceChar = node.attributes[@"fenceChar"];
+  return fenceChar.length > 0 ? fenceChar : @"`";
+}
+
+NSString *ENRMCodeBlockFencedTiptap(NSString *code, NSString *language, NSString *fenceChar)
+{
+  NSString *fence = [@"" stringByPaddingToLength:3 withString:fenceChar startingAtIndex:0];
+  return [NSString stringWithFormat:@"%@%@\n%@\n%@", fence, language ?: @"", code, fence];
+}
+
+NSString *ENRMCodeBlockDisplayLanguageName(NSString *language)
+{
+  if (language.length == 0) {
+    return @"";
+  }
+  return language;
+}
+
+void ENRMApplyCodeBlockTextAttributes(NSMutableAttributedString *string, NSRange range, StyleConfig *config)
+{
+  if (range.length == 0) {
+    return;
+  }
+
+  UIFont *font = [config codeBlockFont];
+  RCTUIColor *color = [config codeBlockColor];
+  if (color) {
+    [string addAttributes:@{NSFontAttributeName : font, NSForegroundColorAttributeName : color} range:range];
+  } else {
+    [string addAttribute:NSFontAttributeName value:font range:range];
+  }
+
+  CGFloat lineHeight = [config codeBlockLineHeight];
+  if (lineHeight > 0) {
+    applyLineHeight(string, range, lineHeight);
+  }
+
+  NSMutableParagraphStyle *paragraphStyle = [getOrCreateParagraphStyle(string, range.location) mutableCopy];
+  paragraphStyle.baseWritingDirection = NSWritingDirectionLeftToRight;
+  paragraphStyle.alignment = NSTextAlignmentLeft;
+  // Re-clamp: unlike paragraphs, code blocks reserve their height analytically as
+  // lineCount * lineHeight (ENRMCodeBlockCodeHeight), so a line must not grow past the
+  // configured lineHeight or a tall run (emoji, wide glyph) would overflow and clip the block.
+  if (lineHeight > 0) {
+    paragraphStyle.maximumLineHeight = lineHeight;
+  }
+  [string addAttribute:NSParagraphStyleAttributeName value:paragraphStyle range:range];
+
+  if (lineHeight > 0) {
+    applyBaselineOffset(string, range);
+  }
+
+  ENRMPinLineMetricsToStyledFonts(string, range);
+}

package/ios/utils/ENRMFeatureFlags.h

@@ -0,0 +1,25 @@
+#pragma once
+
+// Auto-detect RaTeX availability as a fallback for the podspec flag.
+#if __has_include(<RaTeXFFI/ratex.h>) || __has_include("ReactNativeRenderRichText-Swift.h")
+#if !defined(ENRICHED_TIPTAP_MATH)
+#define ENRICHED_TIPTAP_MATH 1
+#endif
+#endif
+
+#if !defined(ENRICHED_TIPTAP_MATH)
+#define ENRICHED_TIPTAP_MATH 0
+#endif
+
+// Code-block syntax highlighting is defined purely by the podspec (no external
+// framework to auto-detect, unlike RaTeX). Default off when the podspec did not
+// enable it; the C++ seam then degrades to no tokens.
+#if !defined(ENRICHED_TIPTAP_CODE_HIGHLIGHT)
+#define ENRICHED_TIPTAP_CODE_HIGHLIGHT 0
+#endif
+
+// Video playback support. Uses AVKit (built into both iOS and macOS — no
+// external framework), so the flag gates only the container view code itself.
+#if !defined(ENRICHED_TIPTAP_VIDEO)
+#define ENRICHED_TIPTAP_VIDEO 0
+#endif

package/ios/utils/ENRMImageDownloader.h

@@ -0,0 +1,30 @@
+#pragma once
+#import "ENRMUIKit.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// Decoded pixel cost, shared by native image caches.
+FOUNDATION_EXPORT NSUInteger ENRMImageByteCost(RCTUIImage *image);
+
+typedef void (^ENRMImageDownloadCompletion)(RCTUIImage *_Nullable image);
+
+/**
+ * Cache identity for a remote image request. Returns the URL itself when no
+ * headers are set; otherwise appends a SHA-256 digest of the sorted header
+ * pairs, so the same URL fetched with different headers is cached and
+ * deduplicated separately without embedding header values in the key.
+ * Header names are compared case-insensitively.
+ */
+NSString *ENRMImageCacheKey(NSString *url, NSDictionary<NSString *, NSString *> *_Nullable headers);
+
+@interface ENRMImageDownloader : NSObject
+
++ (instancetype)shared;
+
+- (void)downloadURL:(NSString *)url
+            headers:(nullable NSDictionary<NSString *, NSString *> *)headers
+         completion:(ENRMImageDownloadCompletion)completion;
+
+@end
+
+NS_ASSUME_NONNULL_END