feat: add retained underlay runtime controls

platform/ios/src/MLNMapView.h

@@ -28,6 +28,21 @@ NS_ASSUME_NONNULL_BEGIN
 @protocol MLNFeature;
 @protocol MLNLocationManager;
 
+/** A pull-based snapshot of one map view's retained-underlay renderer state. */
+MLN_EXPORT
+@interface MLNRetainedUnderlayDiagnostics : NSObject
+
+@property (nonatomic, readonly, getter=isEnabled) BOOL enabled;
+@property (nonatomic, readonly) uint64_t build;
+@property (nonatomic, readonly) uint64_t reuse;
+@property (nonatomic, readonly) uint64_t fallback;
+@property (nonatomic, readonly) uint64_t invalidation;
+@property (nonatomic, copy, readonly) NSString *lastReason;
+
+- (instancetype)init NS_UNAVAILABLE;
+
+@end
+
 /** Options for ``MLNMapView/decelerationRate``. */
 typedef CGFloat MLNMapViewDecelerationRate NS_TYPED_EXTENSIBLE_ENUM;
 
@@ -2266,6 +2281,12 @@ of north, the map will automatically snap to exact north.
  */
 @property (nonatomic) MLNMapDebugMaskOptions debugMask;
 
+/** Enables or disables the map-scoped retained static underlay optimization. */
+@property (nonatomic, getter=isRetainedUnderlayEnabled) BOOL retainedUnderlayEnabled;
+
+/** Returns a thread-safe retained-underlay diagnostics snapshot without enabling periodic events. */
+@property (nonatomic, readonly) MLNRetainedUnderlayDiagnostics *retainedUnderlayDiagnostics;
+
 /**
  Returns the status of the rendering statistics overlay.
  */

platform/ios/src/MLNMapView.mm

@@ -239,6 +239,34 @@ int processIsTranslated() {
 
 #endif
 
+@interface MLNRetainedUnderlayDiagnostics ()
+- (instancetype)initWithEnabled:(BOOL)enabled
+                           build:(uint64_t)build
+                           reuse:(uint64_t)reuse
+                        fallback:(uint64_t)fallback
+                    invalidation:(uint64_t)invalidation
+                      lastReason:(NSString *)lastReason;
+@end
+
+@implementation MLNRetainedUnderlayDiagnostics
+- (instancetype)initWithEnabled:(BOOL)enabled
+                           build:(uint64_t)build
+                           reuse:(uint64_t)reuse
+                        fallback:(uint64_t)fallback
+                    invalidation:(uint64_t)invalidation
+                      lastReason:(NSString *)lastReason {
+  if ((self = [super init])) {
+    _enabled = enabled;
+    _build = build;
+    _reuse = reuse;
+    _fallback = fallback;
+    _invalidation = invalidation;
+    _lastReason = [lastReason copy];
+  }
+  return self;
+}
+@end
+
 class MLNAnnotationContext;
 
 const MLNMapViewDecelerationRate MLNMapViewDecelerationRateNormal =
@@ -3070,6 +3098,32 @@ static void *windowScreenContext = &windowScreenContext;
   self.mbglMap.setDebug(options);
 }
 
+- (BOOL)isRetainedUnderlayEnabled {
+  return _mbglMap ? self.mbglMap.isRetainedUnderlayEnabled() : YES;
+}
+
+- (void)setRetainedUnderlayEnabled:(BOOL)enabled {
+  if (_mbglMap) self.mbglMap.setRetainedUnderlayEnabled(enabled);
+}
+
+- (MLNRetainedUnderlayDiagnostics *)retainedUnderlayDiagnostics {
+  if (!_mbglMap) {
+    return [[MLNRetainedUnderlayDiagnostics alloc] initWithEnabled:YES
+                                                            build:0
+                                                            reuse:0
+                                                         fallback:0
+                                                     invalidation:0
+                                                       lastReason:@"unavailable"];
+  }
+  const auto snapshot = self.mbglMap.getRetainedUnderlayDiagnostics();
+  return [[MLNRetainedUnderlayDiagnostics alloc] initWithEnabled:snapshot.enabled
+                                                          build:snapshot.build
+                                                          reuse:snapshot.reuse
+                                                       fallback:snapshot.fallback
+                                                   invalidation:snapshot.invalidation
+                                                     lastReason:[NSString stringWithUTF8String:snapshot.lastReason.c_str()]];
+}
+
 - (void)resetNorth {
   MLNLogInfo(@"Resetting the map rotation to a northern heading — a direction of 0 degrees.");
   [self resetNorthAnimated:YES];