react-native-enriched-markdown-scaffold 0.7.4-scaffold.9 → 1.0.2-scaffold.2

package/ios/utils/CodeBlockBackground.m

@@ -3,6 +3,11 @@
 #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;
 }
@@ -53,9 +58,18 @@
   if (CGRectIsEmpty(blockRect))
     return;
 
-  blockRect.origin.x = origin.x;
+  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 = textContainer.size.width;
+  blockRect.size.width = availableWidth;
 
   // We extend the background specifically to cover the bottom padding spacer,
   // excluding any additional marginBottom applied via measurement.

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/ENRMBlockMenu.h

@@ -0,0 +1,57 @@
+#pragma once
+#import "ENRMUIKit.h"
+#include <TargetConditionals.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// Selection-menu options that table, math and code block views need for their
+/// own long-press menus. Every field is phrased so that the zero value keeps the
+/// legacy behavior, so a block view that has not received options yet behaves
+/// exactly as before.
+typedef struct {
+  // `selectionMenuConfig.copy.enabled == false`.
+  BOOL copyHidden;
+  // `selectionMenuConfig.copy.format == 'markdown'`: the Copy item writes the
+  // block's Markdown instead of its raw content.
+  BOOL copyWritesMarkdown;
+  // `selectionMenuConfig.copyAsMarkdown.enabled == false`.
+  BOOL copyAsMarkdownHidden;
+  // `selectionMenuConfig.codeBlockCopyButton.enabled == false`.
+  BOOL copyButtonHidden;
+} ENRMBlockMenuOptions;
+
+#if !TARGET_OS_OSX
+/// Builds the long-press menu shared by the table, math and code block views.
+/// Returns nil when no item is left — nil is how UIKit suppresses a context
+/// menu, whereas an empty menu would still lift the view.
+static inline UIContextMenuConfiguration *_Nullable ENRMBlockContextMenuConfiguration(
+    ENRMBlockMenuOptions options, NSString *_Nullable copyLabel, NSString *_Nullable copyAsMarkdownLabel,
+    void (^copyRaw)(void), void (^copyMarkdown)(void))
+{
+  if (options.copyHidden && options.copyAsMarkdownHidden) {
+    return nil;
+  }
+  void (^copyHandler)(void) = options.copyWritesMarkdown ? copyMarkdown : copyRaw;
+  return [UIContextMenuConfiguration
+      configurationWithIdentifier:nil
+                  previewProvider:nil
+                   actionProvider:^UIMenu *(NSArray<UIMenuElement *> *suggestedActions) {
+                     NSMutableArray<UIMenuElement *> *children = [NSMutableArray arrayWithCapacity:2];
+                     if (!options.copyHidden) {
+                       [children addObject:[UIAction actionWithTitle:copyLabel ?: @""
+                                                               image:[RCTUIImage systemImageNamed:@"doc.on.doc"]
+                                                          identifier:nil
+                                                             handler:^(__kindof UIAction *action) { copyHandler(); }]];
+                     }
+                     if (!options.copyAsMarkdownHidden) {
+                       [children addObject:[UIAction actionWithTitle:copyAsMarkdownLabel ?: @""
+                                                               image:[RCTUIImage systemImageNamed:@"doc.text"]
+                                                          identifier:nil
+                                                             handler:^(__kindof UIAction *action) { copyMarkdown(); }]];
+                     }
+                     return [UIMenu menuWithTitle:@"" children:children];
+                   }];
+}
+#endif
+
+NS_ASSUME_NONNULL_END

package/ios/utils/ENRMCodeBlockContent.h

@@ -0,0 +1,37 @@
+#pragma once
+
+#import <Foundation/Foundation.h>
+
+@class MarkdownASTNode;
+@class StyleConfig;
+
+NS_ASSUME_NONNULL_BEGIN
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/// Shared code block node semantics, used by both markdown 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(MarkdownASTNode *node);
+NSString *_Nullable ENRMCodeBlockLanguage(MarkdownASTNode *node);
+NSString *ENRMCodeBlockFenceChar(MarkdownASTNode *node);
+NSString *ENRMCodeBlockFencedMarkdown(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,79 @@
+#import "ENRMCodeBlockContent.h"
+#include "CodeBlockLanguages.hpp"
+#import "ENRMUIKit.h"
+#import "MarkdownASTNode.h"
+#import "ParagraphStyleUtils.h"
+#import "StyleConfig.h"
+
+static void ENRMAppendNodeContent(MarkdownASTNode *node, NSMutableString *output)
+{
+  if (node.content.length > 0) {
+    [output appendString:node.content];
+  }
+  for (MarkdownASTNode *child in node.children) {
+    ENRMAppendNodeContent(child, output);
+  }
+}
+
+NSString *ENRMCodeBlockExtractCode(MarkdownASTNode *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(MarkdownASTNode *node)
+{
+  NSString *language = node.attributes[@"language"];
+  return language.length > 0 ? language : nil;
+}
+
+NSString *ENRMCodeBlockFenceChar(MarkdownASTNode *node)
+{
+  NSString *fenceChar = node.attributes[@"fenceChar"];
+  return fenceChar.length > 0 ? fenceChar : @"`";
+}
+
+NSString *ENRMCodeBlockFencedMarkdown(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 @"";
+  }
+  std::string display = Markdown::displayNameForLanguage(language.UTF8String ?: "");
+  return [NSString stringWithUTF8String:display.c_str()] ?: 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;
+  [string addAttribute:NSParagraphStyleAttributeName value:paragraphStyle range:range];
+}

package/ios/utils/ENRMCodeBlockHighlighter.h

@@ -0,0 +1,37 @@
+#pragma once
+
+#import <Foundation/Foundation.h>
+
+@class StyleConfig;
+
+NS_ASSUME_NONNULL_BEGIN
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/// Platform adapter over the shared C++ syntax highlighting seam
+/// (cpp/highlight/CodeBlockHighlighter.hpp).
+///
+/// Applies token colors as foreground-color attributes onto a mutable copy of
+/// the plain styled code, so highlighting can never change text metrics and
+/// the block height measured from the plain string stays valid. Token colors
+/// come from the config's resolved per-token palette. Returns nil when
+/// highlighting is unavailable (module compiled out, unknown language, parse
+/// failure); callers keep the plain attributed code.
+NSAttributedString *_Nullable ENRMHighlightedAttributedCode(NSAttributedString *plainCode, NSString *code,
+                                                            NSString *_Nullable language, StyleConfig *config);
+
+/// Applies token foreground colors from the config's palette onto `output`
+/// within `range` (range.location is where the code begins in output). Used by
+/// the commonmark flavor, which renders code inline instead of as a container.
+/// Returns whether any color was applied. No-op when highlighting is
+/// unavailable, so callers keep the plain rendering.
+BOOL ENRMApplyHighlightTokens(NSMutableAttributedString *output, NSRange range, NSString *code,
+                              NSString *_Nullable language, StyleConfig *config);
+
+#ifdef __cplusplus
+}
+#endif
+
+NS_ASSUME_NONNULL_END

package/ios/utils/ENRMCodeBlockHighlighter.mm

@@ -0,0 +1,51 @@
+#import "ENRMCodeBlockHighlighter.h"
+#include "CodeBlockHighlighter.hpp"
+#import "ENRMUIKit.h"
+#import "StyleConfig.h"
+
+BOOL ENRMApplyHighlightTokens(NSMutableAttributedString *output, NSRange range, NSString *code,
+                              NSString *_Nullable language, StyleConfig *config)
+{
+  if (code.length == 0) {
+    return NO;
+  }
+
+  std::vector<Markdown::HighlightToken> tokens;
+  try {
+    tokens = Markdown::highlightCode(code.UTF8String ?: "", language.UTF8String ?: "");
+  } catch (...) {
+    return NO;
+  }
+  if (tokens.empty()) {
+    return NO;
+  }
+
+  NSUInteger cap = MIN(NSMaxRange(range), output.length);
+  BOOL applied = NO;
+  for (const auto &token : tokens) {
+    RCTUIColor *color = [config codeBlockSyntaxColorForToken:(NSInteger)token.type];
+    if (!color || token.end <= token.start) {
+      continue;
+    }
+    NSUInteger start = range.location + token.start;
+    NSUInteger end = range.location + token.end;
+    if (end > cap) {
+      continue;
+    }
+    [output addAttribute:NSForegroundColorAttributeName value:color range:NSMakeRange(start, end - start)];
+    applied = YES;
+  }
+  return applied;
+}
+
+NSAttributedString *ENRMHighlightedAttributedCode(NSAttributedString *plainCode, NSString *code,
+                                                  NSString *_Nullable language, StyleConfig *config)
+{
+  if (code.length == 0) {
+    return nil;
+  }
+
+  NSMutableAttributedString *highlighted = [plainCode mutableCopy];
+  BOOL applied = ENRMApplyHighlightTokens(highlighted, NSMakeRange(0, highlighted.length), code, language, config);
+  return applied ? highlighted : nil;
+}

package/ios/utils/ENRMFeatureFlags.h

@@ -10,3 +10,10 @@
 #if !defined(ENRICHED_MARKDOWN_MATH)
 #define ENRICHED_MARKDOWN_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_MARKDOWN_CODE_HIGHLIGHT)
+#define ENRICHED_MARKDOWN_CODE_HIGHLIGHT 0
+#endif

package/ios/utils/ENRMImageDownloader.h

@@ -5,11 +5,21 @@ NS_ASSUME_NONNULL_BEGIN
 
 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.
+ */
+NSString *ENRMImageCacheKey(NSString *url, NSDictionary<NSString *, NSString *> *_Nullable headers);
+
 @interface ENRMImageDownloader : NSObject
 
 + (instancetype)shared;
 
-- (void)downloadURL:(NSString *)url completion:(ENRMImageDownloadCompletion)completion;
+- (void)downloadURL:(NSString *)url
+            headers:(nullable NSDictionary<NSString *, NSString *> *)headers
+         completion:(ENRMImageDownloadCompletion)completion;
 
 @end
 

package/ios/utils/ENRMImageDownloader.m

@@ -1,5 +1,7 @@
 #import "ENRMImageDownloader.h"
 #import "ENRMImageAttachment.h"
+#import "ENRMLocalImageLoader.h"
+#import <CommonCrypto/CommonDigest.h>
 #include <TargetConditionals.h>
 
 static const NSUInteger kDiskCacheMemoryCapacity = 10 * 1024 * 1024;
@@ -13,6 +15,27 @@ static inline NSUInteger ENRMImageByteCost(RCTUIImage *image)
   return CGImageGetBytesPerRow(cgImage) * CGImageGetHeight(cgImage);
 }
 
+NSString *ENRMImageCacheKey(NSString *url, NSDictionary<NSString *, NSString *> *headers)
+{
+  if (headers.count == 0) {
+    return url;
+  }
+  NSArray<NSString *> *names = [headers.allKeys sortedArrayUsingSelector:@selector(compare:)];
+  NSMutableArray<NSString *> *pairs = [NSMutableArray arrayWithCapacity:names.count];
+  for (NSString *name in names) {
+    [pairs addObject:[NSString stringWithFormat:@"%@:%@", name, headers[name]]];
+  }
+  NSString *joined = [pairs componentsJoinedByString:@"\n"];
+  NSData *data = [joined dataUsingEncoding:NSUTF8StringEncoding];
+  unsigned char digest[CC_SHA256_DIGEST_LENGTH];
+  CC_SHA256(data.bytes, (CC_LONG)data.length, digest);
+  NSMutableString *hash = [NSMutableString stringWithCapacity:CC_SHA256_DIGEST_LENGTH * 2];
+  for (int i = 0; i < CC_SHA256_DIGEST_LENGTH; i++) {
+    [hash appendFormat:@"%02x", digest[i]];
+  }
+  return [NSString stringWithFormat:@"%@|%@", url, hash];
+}
+
 @implementation ENRMImageDownloader {
   NSURLSession *_session;
   NSMutableDictionary<NSString *, NSMutableArray<ENRMImageDownloadCompletion> *> *_inFlightRequests;
@@ -43,56 +66,77 @@ static inline NSUInteger ENRMImageByteCost(RCTUIImage *image)
   return self;
 }
 
-- (void)downloadURL:(NSString *)url completion:(ENRMImageDownloadCompletion)completion
+- (void)downloadURL:(NSString *)url
+            headers:(NSDictionary<NSString *, NSString *> *)headers
+         completion:(ENRMImageDownloadCompletion)completion
 {
   if (url.length == 0) {
     completion(nil);
     return;
   }
 
-  RCTUIImage *cached = [[ENRMImageAttachment originalImageCache] objectForKey:url];
+  BOOL isLocal = ENRMIsLocalImageURL(url);
+  NSString *cacheKey = isLocal ? url : ENRMImageCacheKey(url, headers);
+
+  RCTUIImage *cached = [[ENRMImageAttachment originalImageCache] objectForKey:cacheKey];
   if (cached) {
     completion(cached);
     return;
   }
 
+  if (isLocal) {
+    RCTUIImage *local = ENRMLoadLocalImage(url);
+    if (local) {
+      [[ENRMImageAttachment originalImageCache] setObject:local forKey:cacheKey cost:ENRMImageByteCost(local)];
+    }
+    completion(local);
+    return;
+  }
+
   @synchronized(_inFlightRequests) {
-    NSMutableArray *existing = _inFlightRequests[url];
+    NSMutableArray *existing = _inFlightRequests[cacheKey];
     if (existing) {
       [existing addObject:completion];
       return;
     }
-    _inFlightRequests[url] = [NSMutableArray arrayWithObject:completion];
+    _inFlightRequests[cacheKey] = [NSMutableArray arrayWithObject:completion];
   }
 
   NSURL *nsURL = [NSURL URLWithString:url];
   if (!nsURL) {
-    [self dispatchCallbacksForURL:url image:nil];
+    [self dispatchCallbacksForKey:cacheKey image:nil];
     return;
   }
 
-  [[_session dataTaskWithURL:nsURL
-           completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
+  NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:nsURL];
+  [headers enumerateKeysAndObjectsUsingBlock:^(NSString *name, NSString *value, BOOL *stop) {
+    [request setValue:value forHTTPHeaderField:name];
+  }];
+
+  [[_session dataTaskWithRequest:request
+               completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
 #if !TARGET_OS_OSX
-             RCTUIImage *image = (data && !error) ? [RCTUIImage imageWithData:data] : nil;
+                 RCTUIImage *image = (data && !error) ? [RCTUIImage imageWithData:data] : nil;
 #else
         RCTUIImage *image = (data && !error) ? [[RCTUIImage alloc] initWithData:data] : nil;
 #endif
 
-             if (image) {
-               [[ENRMImageAttachment originalImageCache] setObject:image forKey:url cost:ENRMImageByteCost(image)];
-             }
+                 if (image) {
+                   [[ENRMImageAttachment originalImageCache] setObject:image
+                                                                forKey:cacheKey
+                                                                  cost:ENRMImageByteCost(image)];
+                 }
 
-             [self dispatchCallbacksForURL:url image:image];
-           }] resume];
+                 [self dispatchCallbacksForKey:cacheKey image:image];
+               }] resume];
 }
 
-- (void)dispatchCallbacksForURL:(NSString *)url image:(RCTUIImage *_Nullable)image
+- (void)dispatchCallbacksForKey:(NSString *)cacheKey image:(RCTUIImage *_Nullable)image
 {
   NSArray<ENRMImageDownloadCompletion> *callbacks;
   @synchronized(_inFlightRequests) {
-    callbacks = [_inFlightRequests[url] copy];
-    [_inFlightRequests removeObjectForKey:url];
+    callbacks = [_inFlightRequests[cacheKey] copy];
+    [_inFlightRequests removeObjectForKey:cacheKey];
   }
 
   if (!callbacks)

package/ios/utils/ENRMLocalImageLoader.h

@@ -0,0 +1,31 @@
+#pragma once
+#import "ENRMUIKit.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * Local (non-network) image loading for markdown sources (issue #377).
+ *
+ * React Native's asset system resolves `require('./img.png')` to a Metro http
+ * URL in dev, but to a `file://` URL near the app bundle in release builds
+ * (`AssetSourceResolver.scaledAssetURLNearBundle`), and libraries like
+ * expo-asset also hand out percent-encoded `file://` paths in the caches
+ * directory. These should not go through NSURLSession + NSURLCache: they gain
+ * nothing from HTTP caching or timeouts, and bundle assets lose `@2x`/`@3x`
+ * scale selection and asset-catalog resolution.
+ *
+ * Resolution mirrors RN's RCTImageFromLocalAssetURL: bundle-relative names are
+ * tried with `imageNamed:` first (scale suffixes, asset catalogs, and system
+ * caching for free), then the loader falls back to loading the file directly,
+ * appending `.png` when the path has no extension.
+ */
+
+/// YES when the URL refers to a non-network source: any `file://` URL, or a
+/// scheme-less string (bare bundle-relative asset name or absolute path).
+BOOL ENRMIsLocalImageURL(NSString *url);
+
+/// Synchronously loads a local image; returns nil when the source cannot be
+/// resolved. Safe to call off the main thread.
+RCTUIImage *_Nullable ENRMLoadLocalImage(NSString *url);
+
+NS_ASSUME_NONNULL_END

package/ios/utils/ENRMLocalImageLoader.m

@@ -0,0 +1,68 @@
+#import "ENRMLocalImageLoader.h"
+
+static NSString *_Nullable ENRMBundleRelativePath(NSString *path)
+{
+  NSString *bundlePath = [[NSBundle mainBundle] resourcePath];
+  if (bundlePath == nil || ![path hasPrefix:bundlePath]) {
+    return nil;
+  }
+  NSString *relative = [path substringFromIndex:bundlePath.length];
+  return [relative hasPrefix:@"/"] ? [relative substringFromIndex:1] : relative;
+}
+
+static RCTUIImage *_Nullable ENRMImageNamed(NSString *name)
+{
+  return [RCTUIImage imageNamed:name];
+}
+
+static RCTUIImage *_Nullable ENRMImageAtPath(NSString *path)
+{
+  if (path.pathExtension.length == 0) {
+    path = [path stringByAppendingPathExtension:@"png"];
+  }
+#if !TARGET_OS_OSX
+  return [RCTUIImage imageWithContentsOfFile:path];
+#else
+  return [[RCTUIImage alloc] initWithContentsOfFile:path];
+#endif
+}
+
+BOOL ENRMIsLocalImageURL(NSString *url)
+{
+  if ([url hasPrefix:@"file://"]) {
+    return YES;
+  }
+  NSURL *parsed = [NSURL URLWithString:url];
+  return parsed == nil || parsed.scheme.length == 0;
+}
+
+RCTUIImage *_Nullable ENRMLoadLocalImage(NSString *url)
+{
+  NSString *filePath = nil;
+  NSString *imageName = nil;
+
+  if ([url hasPrefix:@"file://"]) {
+    NSURL *fileURL = [NSURL URLWithString:url];
+    if (fileURL.fileURL) {
+      filePath = @(fileURL.fileSystemRepresentation);
+    } else {
+      NSString *stripped = [url substringFromIndex:@"file://".length];
+      filePath = [stripped stringByRemovingPercentEncoding] ?: stripped;
+    }
+    imageName = ENRMBundleRelativePath(filePath);
+  } else {
+    NSString *decoded = [url stringByRemovingPercentEncoding] ?: url;
+    if (decoded.absolutePath) {
+      filePath = decoded;
+    } else {
+      imageName = decoded;
+      filePath = [[[NSBundle mainBundle] resourcePath] stringByAppendingPathComponent:decoded];
+    }
+  }
+
+  RCTUIImage *image = imageName.length > 0 ? ENRMImageNamed(imageName) : nil;
+  if (image == nil && filePath.length > 0) {
+    image = ENRMImageAtPath(filePath);
+  }
+  return image;
+}

package/ios/utils/ENRMMathFallback.h

@@ -0,0 +1,26 @@
+#pragma once
+#import "ENRMUIKit.h"
+#import <Foundation/Foundation.h>
+
+static const CGFloat kENRMMathFallbackDefaultFontSize = 16.0;
+
+NS_ASSUME_NONNULL_BEGIN
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Builds the visible-source fallback for a RaTeX parse failure: the original
+ * LaTeX source wrapped in its delimiters ($ inline, $$ block), typeset in body
+ * style. A parse failure must never render as an invisible zero-size box —
+ * the formula stays visible and copyable instead.
+ */
+NSAttributedString *ENRMMathFallbackString(NSString *_Nullable latex, NSString *delimiter, CGFloat fontSize,
+                                           RCTUIColor *_Nullable color);
+
+#ifdef __cplusplus
+}
+#endif
+
+NS_ASSUME_NONNULL_END

package/ios/utils/ENRMMathFallback.m

@@ -0,0 +1,18 @@
+#import "ENRMMathFallback.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+NSAttributedString *ENRMMathFallbackString(NSString *_Nullable latex, NSString *delimiter, CGFloat fontSize,
+                                           RCTUIColor *_Nullable color)
+{
+  CGFloat size = fontSize > 0 ? fontSize : kENRMMathFallbackDefaultFontSize;
+  UIFont *font = [UIFont systemFontOfSize:size];
+  NSString *source = [NSString stringWithFormat:@"%@%@%@", delimiter, latex ?: @"", delimiter];
+  return [[NSAttributedString alloc] initWithString:source
+                                         attributes:@{
+                                           NSFontAttributeName : font,
+                                           NSForegroundColorAttributeName : color ?: [RCTUIColor blackColor],
+                                         }];
+}
+
+NS_ASSUME_NONNULL_END