rn-iconify 2.2.1 → 3.0.0

package/lib/module/createIconSet.js

@@ -1,11 +1,17 @@
+function _extends() { return _extends = Object.assign ? Object.assign.bind() : function (n) { for (var e = 1; e < arguments.length; e++) { var t = arguments[e]; for (var r in t) ({}).hasOwnProperty.call(t, r) && (n[r] = t[r]); } return n; }, _extends.apply(null, arguments); }
 /**
  * createIconSet - Factory function for creating typed icon components
+ *
+ * v3.0 rewrite:
+ * - React.memo + React.forwardRef
+ * - useMergedIconProps (replaces inline ?? chains)
+ * - Rest spread (new props automatically forwarded)
+ * - Fuzzy matching in __DEV__ for typo suggestions
  */
 
 import React from 'react';
 import { IconRenderer } from './IconRenderer';
-import { useIconTheme } from './theme';
-import { DEFAULT_ICON_THEME } from './theme/types';
+import { useMergedIconProps } from './theme';
 /**
  * Capitalize first letter of a string
  */
@@ -26,6 +32,46 @@ function toPascalCase(str) {
  * This allows for sanitized keys like `_500px` to map to original names like `500px`
  */
 
+/**
+ * Simple Levenshtein distance for __DEV__ fuzzy matching
+ * Only used for "Did you mean?" suggestions on typos
+ */
+function levenshtein(a, b) {
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  const matrix = [];
+  for (let i = 0; i <= b.length; i++) {
+    matrix[i] = [i];
+  }
+  for (let j = 0; j <= a.length; j++) {
+    matrix[0][j] = j;
+  }
+  for (let i = 1; i <= b.length; i++) {
+    for (let j = 1; j <= a.length; j++) {
+      const cost = b[i - 1] === a[j - 1] ? 0 : 1;
+      matrix[i][j] = Math.min(matrix[i - 1][j] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j - 1] + cost);
+    }
+  }
+  return matrix[b.length][a.length];
+}
+
+/**
+ * Find the closest icon name within a reasonable edit distance
+ */
+function findClosestMatch(name, validNames) {
+  let bestMatch = null;
+  let bestDistance = Infinity;
+  const maxDistance = Math.max(2, Math.floor(name.length * 0.4));
+  for (const validName of validNames) {
+    const distance = levenshtein(name, validName);
+    if (distance < bestDistance && distance <= maxDistance) {
+      bestDistance = distance;
+      bestMatch = validName;
+    }
+  }
+  return bestMatch;
+}
+
 /**
  * Create a typed icon component for a specific icon set
  *
@@ -45,105 +91,35 @@ function toPascalCase(str) {
  * ```
  */
 export function createIconSet(prefix, iconNames) {
-  /**
-   * Icon component for the specific icon set
-   */
-  function IconComponent({
+  // Cache valid names for fuzzy matching (only computed once per icon set)
+  let cachedValidNames = null;
+  const IconComponent = /*#__PURE__*/React.memo(/*#__PURE__*/React.forwardRef(function IconComponent({
     name,
-    size,
-    color,
-    width,
-    height,
-    style,
-    className,
-    rotate,
-    flip,
-    fallback,
-    fallbackDelay,
-    placeholder,
-    placeholderColor,
-    placeholderDuration,
-    onLoad,
-    onError,
     accessibilityLabel,
-    testID,
-    // Press props
-    onPress,
-    onLongPress,
-    onPressIn,
-    onPressOut,
-    disabled,
-    pressedStyle,
-    // Animation props
-    animate,
-    animationDuration,
-    animationLoop,
-    animationEasing,
-    animationDelay,
-    autoPlay,
-    onAnimationComplete
-  }) {
-    // Get theme defaults
-    const {
-      theme
-    } = useIconTheme();
+    ...restProps
+  }, ref) {
+    // Merge with theme defaults (memoized internally)
+    const mergedProps = useMergedIconProps(restProps);
 
-    // Merge props with theme defaults (props take precedence)
-    const mergedSize = size ?? theme.size ?? DEFAULT_ICON_THEME.size;
-    const mergedColor = color ?? theme.color ?? DEFAULT_ICON_THEME.color;
-    const mergedRotate = rotate ?? theme.rotate ?? DEFAULT_ICON_THEME.rotate;
-    const mergedFlip = flip ?? theme.flip;
-    const mergedFallbackDelay = fallbackDelay ?? theme.fallbackDelay ?? DEFAULT_ICON_THEME.fallbackDelay;
-    const mergedPlaceholder = placeholder ?? theme.placeholder;
-    const mergedPlaceholderColor = placeholderColor ?? theme.placeholderColor ?? DEFAULT_ICON_THEME.placeholderColor;
-    const mergedPlaceholderDuration = placeholderDuration ?? theme.placeholderDuration ?? DEFAULT_ICON_THEME.placeholderDuration;
-
-    // Runtime validation for icon name
+    // Runtime validation with fuzzy matching
     if (__DEV__ && !(name in iconNames)) {
-      console.warn(`[rn-iconify] Invalid icon name "${name}" for prefix "${prefix}". ` + `Check if the icon exists in the icon set.`);
+      if (!cachedValidNames) {
+        cachedValidNames = Object.keys(iconNames);
+      }
+      const suggestion = findClosestMatch(name, cachedValidNames);
+      const suggestionText = suggestion ? ` Did you mean "${suggestion}"?` : '';
+      console.warn(`[rn-iconify] Unknown icon name "${name}" for ${toPascalCase(prefix)}.${suggestionText}`);
     }
 
     // Get the actual icon name (handles mapped names like _500px -> "500px")
     const actualName = iconNames[name] === true ? name : iconNames[name];
     const iconName = `${prefix}:${actualName}`;
-    return /*#__PURE__*/React.createElement(IconRenderer, {
+    return /*#__PURE__*/React.createElement(IconRenderer, _extends({
+      ref: ref,
       iconName: iconName,
-      size: mergedSize,
-      color: mergedColor,
-      width: width,
-      height: height,
-      style: style,
-      className: className,
-      rotate: mergedRotate,
-      flip: mergedFlip,
-      fallback: fallback,
-      fallbackDelay: mergedFallbackDelay,
-      placeholder: mergedPlaceholder,
-      placeholderColor: mergedPlaceholderColor,
-      placeholderDuration: mergedPlaceholderDuration,
-      onLoad: onLoad,
-      onError: onError,
-      accessibilityLabel: accessibilityLabel ?? name,
-      testID: testID
-      // Press props
-      ,
-      onPress: onPress,
-      onLongPress: onLongPress,
-      onPressIn: onPressIn,
-      onPressOut: onPressOut,
-      disabled: disabled,
-      pressedStyle: pressedStyle
-      // Animation props
-      ,
-      animate: animate,
-      animationDuration: animationDuration,
-      animationLoop: animationLoop,
-      animationEasing: animationEasing,
-      animationDelay: animationDelay,
-      autoPlay: autoPlay,
-      onAnimationComplete: onAnimationComplete
-    });
-  }
+      accessibilityLabel: accessibilityLabel ?? name
+    }, mergedProps));
+  }));
 
   // Set display name for debugging
   IconComponent.displayName = `${toPascalCase(prefix)}Icon`;

package/lib/module/dev/index.js

@@ -0,0 +1,16 @@
+/**
+ * rn-iconify/dev
+ * Development-only utilities for exploring and profiling icons.
+ * These are separated from the main entry point to avoid bloating production bundles.
+ *
+ * @example
+ * ```tsx
+ * import { IconExplorer, PerformanceMonitor } from 'rn-iconify/dev';
+ * ```
+ */
+
+// Icon Explorer
+export { IconExplorer, ExplorerContext, useExplorerContext, useExplorer, getAllIconSets, getIconSetByPrefix, getIconSetsByCategory, searchIconSets, generateImportStatement, generateIconJSX, POPULAR_ICON_SETS, DEFAULT_PREVIEW_CONFIG, DEFAULT_EXPLORER_CONFIG } from '../explorer';
+// Performance Monitoring
+export { PerformanceMonitor, enablePerformanceMonitoring, disablePerformanceMonitoring, getPerformanceReport, printPerformanceReport } from '../performance';
+//# sourceMappingURL=index.js.map

package/lib/module/errors.js

@@ -0,0 +1,13 @@
+/**
+ * Typed error classes for rn-iconify
+ * Consumers can use error.code to distinguish error types
+ */
+
+export class IconLoadError extends Error {
+  name = 'IconLoadError';
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+//# sourceMappingURL=errors.js.map

package/lib/module/index.js

@@ -16,6 +16,9 @@
 // Icon Set Components (200+ sets, 268,000+ icons)
 export * from './components';
 
+// Errors
+export { IconLoadError } from './errors';
+
 // Core Types
 
 // Placeholder Components
@@ -43,12 +46,16 @@ export { fetchIcon, fetchIconsBatch, parseIconName, checkAPIHealth, getAPIBaseUr
 export { getNativeIconify, isNativeModuleAvailable } from './native';
 // Offline Bundle
 export { loadOfflineBundle, loadOfflineBundleAsync, isBundleCompatible, getBundleStats } from './bundle';
-// Performance Monitoring
-export { PerformanceMonitor, enablePerformanceMonitoring, disablePerformanceMonitoring, getPerformanceReport, printPerformanceReport } from './performance';
+
+// Performance Monitoring — runtime exports moved to 'rn-iconify/dev'
+// Types kept here for type-only consumers
+
 // Accessibility
 export { AccessibilityProvider, AccessibilityContext, useAccessibilityContext, useAccessibility, useAccessibleIcon, withAccessibility, defaultLabelGenerator, adjustForHighContrast, meetsContrastRequirement, getHighContrastAlternative, calculateTouchTargetPadding, DEFAULT_ACCESSIBILITY_CONFIG } from './accessibility';
-// Icon Explorer (Dev Mode)
-export { IconExplorer, ExplorerContext, useExplorerContext, useExplorer, getAllIconSets, getIconSetByPrefix, getIconSetsByCategory, searchIconSets, generateImportStatement, generateIconJSX, POPULAR_ICON_SETS, DEFAULT_PREVIEW_CONFIG, DEFAULT_EXPLORER_CONFIG } from './explorer';
+
+// Icon Explorer — runtime exports moved to 'rn-iconify/dev'
+// Types kept here for type-only consumers
+
 /**
  * Prefetch multiple icons into cache
  * Useful for preloading icons before they're needed

package/lib/module/network/IconifyAPI.js

@@ -5,6 +5,7 @@
  */
 
 import { ConfigManager } from '../config';
+import { IconLoadError } from '../errors';
 
 /**
  * Get current API configuration
@@ -174,15 +175,28 @@ function buildSvg(data, defaultWidth = 24, defaultHeight = 24) {
  */
 export async function fetchIcon(iconName, signal) {
   // Check for pending request (deduplication)
+  // If a request is already in flight, reuse it but isolate the abort signal
+  // so that one component's unmount doesn't cancel another's fetch
   const pending = pendingRequests.get(iconName);
   if (pending) {
+    if (signal) {
+      return Promise.race([pending, new Promise((_, reject) => {
+        if (signal.aborted) {
+          reject(new DOMException('Aborted', 'AbortError'));
+          return;
+        }
+        signal.addEventListener('abort', () => reject(new DOMException('Aborted', 'AbortError')), {
+          once: true
+        });
+      })]);
+    }
     return pending;
   }
 
   // Parse icon name
   const parsed = parseIconName(iconName);
   if (!parsed) {
-    throw new Error(`Invalid icon name format: "${iconName}". Expected "prefix:name" format.`);
+    throw new IconLoadError('INVALID_NAME', `Invalid icon name format: "${iconName}". Expected "prefix:name" format.`);
   }
   const {
     prefix,
@@ -207,19 +221,22 @@ export async function fetchIcon(iconName, signal) {
           signal
         });
         if (!response.ok) {
-          throw new Error(`HTTP ${response.status}: Failed to fetch icon "${iconName}"`);
+          if (response.status === 404) {
+            throw new IconLoadError('NOT_FOUND', `Icon "${iconName}" not found (HTTP 404)`);
+          }
+          throw new IconLoadError('NETWORK', `HTTP ${response.status}: Failed to fetch icon "${iconName}"`);
         }
         const data = await response.json();
 
         // Validate response structure
         if (!data || typeof data !== 'object' || !data.icons) {
-          throw new Error(`Invalid API response for icon "${iconName}"`);
+          throw new IconLoadError('NETWORK', `Invalid API response for icon "${iconName}"`);
         }
 
         // Check if icon exists in response
         const iconData = data.icons[name];
         if (!iconData) {
-          throw new Error(`Icon "${iconName}" not found in Iconify API response`);
+          throw new IconLoadError('NOT_FOUND', `Icon "${iconName}" not found in Iconify API response`);
         }
 
         // Build SVG from icon data
@@ -227,7 +244,7 @@ export async function fetchIcon(iconName, signal) {
 
         // Validate SVG output
         if (!isValidSvg(svg)) {
-          throw new Error(`Invalid SVG generated for icon "${iconName}"`);
+          throw new IconLoadError('INVALID_SVG', `Invalid SVG generated for icon "${iconName}"`);
         }
         return svg;
       } catch (error) {
@@ -241,7 +258,13 @@ export async function fetchIcon(iconName, signal) {
             throw error;
           }
         }
-        lastError = error instanceof Error ? error : new Error(String(error));
+
+        // Convert timeout aborts to typed error
+        if (error instanceof Error && error.name === 'AbortError' && !signal?.aborted) {
+          lastError = new IconLoadError('TIMEOUT', `Timeout fetching icon "${iconName}"`);
+        } else {
+          lastError = error instanceof Error ? error : new IconLoadError('NETWORK', String(error));
+        }
 
         // Wait before retrying (except on last attempt)
         if (attempt < settings.retries) {
@@ -375,14 +398,15 @@ export async function fetchIconsBatch(iconNames, signal) {
 
 /**
  * Check if Iconify API is reachable
+ * @param timeoutMs Timeout in milliseconds (default: 5000)
  */
-export async function checkAPIHealth() {
+export async function checkAPIHealth(timeoutMs = 5000) {
   const settings = getAPISettings();
   try {
-    const response = await fetch(`${settings.baseUrl}/collections`, {
+    const response = await fetchWithTimeout(`${settings.baseUrl}/collections`, {
       method: 'HEAD',
       headers: settings.headers
-    });
+    }, timeoutMs);
     return response.ok;
   } catch {
     return false;

package/lib/module/placeholder/Shimmer.js

@@ -1,15 +1,36 @@
 /**
  * Shimmer Placeholder Component
- * Animated gradient sweep effect while icon is loading
+ * Animated gradient-like sweep effect while icon is loading
+ *
+ * Uses 3 overlapping bars with staggered opacity to simulate a gradient,
+ * without requiring any external gradient library.
  */
 
-import React, { memo, useEffect, useRef } from 'react';
+import React, { memo, useEffect, useRef, useMemo } from 'react';
 import { Animated, StyleSheet, View, Easing } from 'react-native';
 import { DEFAULT_PLACEHOLDER_CONFIG } from './types';
 /**
- * Shimmer placeholder - animated light sweep effect
- * Provides prominent visual feedback during loading
- * Uses translateX animation for smooth performance
+ * Bar configuration for the gradient-like shimmer
+ * Each bar has a different width and opacity, staggered in time
+ */
+const SHIMMER_BARS = [{
+  widthFactor: 0.5,
+  opacity: 0.15,
+  delay: 0
+}, {
+  widthFactor: 0.35,
+  opacity: 0.3,
+  delay: 0.15
+}, {
+  widthFactor: 0.2,
+  opacity: 0.5,
+  delay: 0.3
+}];
+
+/**
+ * Shimmer placeholder - animated gradient-like sweep effect
+ * 3 overlapping bars create a soft gradient without native dependencies
+ * Uses translateX animation for smooth 60fps performance
  */
 function ShimmerComponent({
   width,
@@ -20,30 +41,41 @@ function ShimmerComponent({
   borderRadius = DEFAULT_PLACEHOLDER_CONFIG.borderRadius,
   testID
 }) {
-  const translateX = useRef(new Animated.Value(-width)).current;
+  // One Animated.Value per bar for staggered animation
+  const bar0 = useRef(new Animated.Value(-width)).current;
+  const bar1 = useRef(new Animated.Value(-width)).current;
+  const bar2 = useRef(new Animated.Value(-width)).current;
+  const bars = useMemo(() => [bar0, bar1, bar2], [bar0, bar1, bar2]);
   const animationRef = useRef(null);
   useEffect(() => {
-    // Reset animation when width changes
-    translateX.setValue(-width);
+    // Reset all bars
+    for (const bar of bars) {
+      bar.setValue(-width);
+    }
 
-    // Create looping shimmer animation
-    animationRef.current = Animated.loop(Animated.timing(translateX, {
+    // Create staggered looping animations
+    const animations = SHIMMER_BARS.map((config, i) => Animated.loop(Animated.sequence([
+    // Stagger delay
+    ...(config.delay > 0 ? [Animated.delay(duration * config.delay)] : []), Animated.timing(bars[i], {
       toValue: width,
-      duration: duration,
-      easing: Easing.linear,
+      duration: duration * (1 - config.delay),
+      easing: Easing.inOut(Easing.ease),
       useNativeDriver: true
-    }));
+    }),
+    // Reset for next loop iteration
+    Animated.timing(bars[i], {
+      toValue: -width,
+      duration: 0,
+      useNativeDriver: true
+    })])));
+    animationRef.current = Animated.parallel(animations);
     animationRef.current.start();
     return () => {
-      // Clean up animation on unmount
       if (animationRef.current) {
         animationRef.current.stop();
       }
     };
-  }, [translateX, width, duration]);
-
-  // Calculate shimmer bar width (30% of container width)
-  const shimmerWidth = Math.max(width * 0.3, 20);
+  }, [bars, width, duration]);
   return /*#__PURE__*/React.createElement(View, {
     style: [styles.container, {
       width,
@@ -55,16 +87,18 @@ function ShimmerComponent({
     accessibilityRole: "none",
     accessibilityElementsHidden: true,
     importantForAccessibility: "no"
-  }, /*#__PURE__*/React.createElement(Animated.View, {
+  }, SHIMMER_BARS.map((config, i) => /*#__PURE__*/React.createElement(Animated.View, {
+    key: i,
     style: [styles.shimmer, {
-      width: shimmerWidth,
+      width: Math.max(width * config.widthFactor, 12),
       height,
       backgroundColor: highlightColor,
+      opacity: config.opacity,
       transform: [{
-        translateX
+        translateX: bars[i]
       }]
     }]
-  }));
+  })));
 }
 const styles = StyleSheet.create({
   container: {
@@ -74,8 +108,7 @@ const styles = StyleSheet.create({
   shimmer: {
     position: 'absolute',
     top: 0,
-    left: 0,
-    opacity: 0.5
+    left: 0
   }
 });
 

package/lib/module/theme/IconThemeProvider.js

@@ -1,6 +1,10 @@
 /**
  * IconThemeProvider
  * Provides global theme configuration for all icon components
+ *
+ * v3.0 fix: Replaced useState + useEffect anti-pattern with useMemo.
+ * Inline theme props no longer cause infinite re-render loops.
+ * setTheme() still works for dynamic theme switching via internal override state.
  */
 
 import React, { useState, useMemo, useCallback, memo } from 'react';
@@ -24,20 +28,6 @@ import { IconThemeContext, mergeWithDefaults } from './context';
  * }
  * ```
  *
- * @example With placeholder defaults
- * ```tsx
- * <IconThemeProvider
- *   theme={{
- *     size: 24,
- *     color: '#1a1a1a',
- *     placeholder: 'shimmer',
- *     placeholderColor: '#f0f0f0',
- *   }}
- * >
- *   <YourApp />
- * </IconThemeProvider>
- * ```
- *
  * @example Dynamic theme switching
  * ```tsx
  * function App() {
@@ -60,26 +50,36 @@ function IconThemeProviderComponent({
   theme: initialTheme,
   children
 }) {
-  const [theme, setThemeState] = useState(() => mergeWithDefaults(initialTheme));
+  // Derive theme from prop (no useState + useEffect cycle)
+  const externalTheme = useMemo(() => mergeWithDefaults(initialTheme), [initialTheme]);
 
-  // Memoized setTheme that supports both direct value and updater function
+  // Internal override state for setTheme() API
+  const [overrideTheme, setOverrideTheme] = useState(null);
+
+  // When external theme changes, clear any override
+  const prevExternalRef = React.useRef(externalTheme);
+  if (prevExternalRef.current !== externalTheme) {
+    prevExternalRef.current = externalTheme;
+    if (overrideTheme !== null) {
+      setOverrideTheme(null);
+    }
+  }
+  const effectiveTheme = overrideTheme ?? externalTheme;
+
+  // setTheme supports both direct value and updater function
   const setTheme = useCallback(newTheme => {
-    setThemeState(prevTheme => {
-      const nextTheme = typeof newTheme === 'function' ? newTheme(prevTheme) : newTheme;
+    setOverrideTheme(prevOverride => {
+      const current = prevOverride ?? externalTheme;
+      const nextTheme = typeof newTheme === 'function' ? newTheme(current) : newTheme;
       return mergeWithDefaults(nextTheme);
     });
-  }, []);
-
-  // Update internal state when prop changes
-  React.useEffect(() => {
-    setThemeState(mergeWithDefaults(initialTheme));
-  }, [initialTheme]);
+  }, [externalTheme]);
 
   // Memoize context value to prevent unnecessary re-renders
   const contextValue = useMemo(() => ({
-    theme,
+    theme: effectiveTheme,
     setTheme
-  }), [theme, setTheme]);
+  }), [effectiveTheme, setTheme]);
   return /*#__PURE__*/React.createElement(IconThemeContext.Provider, {
     value: contextValue
   }, children);

package/lib/typescript/IconRenderer.d.ts

@@ -1,8 +1,17 @@
 /**
  * IconRenderer - Core component for rendering SVG icons
- * Handles cache lookup, network fetching, and SVG rendering
+ * Handles cache lookup, network fetching, placeholders, and SVG rendering
+ *
+ * v3.0 rewrite:
+ * - useReducer state machine (eliminates impossible states)
+ * - SvgXml color prop (preserves multi-color icons)
+ * - React.memo + React.forwardRef
+ * - Stable loadIcon deps (only iconName triggers refetch)
+ * - Auto 44dp hitSlop for small icons
+ * - Typed IconLoadError
  */
 import React from 'react';
+import { View } from 'react-native';
 import type { IconRendererProps } from './types';
-export declare function IconRenderer({ iconName, size, color, width: propWidth, height: propHeight, style, className, rotate, flip, fallback, fallbackDelay, placeholder, placeholderColor, placeholderDuration, onLoad, onError, accessibilityLabel, testID, onPress, onLongPress, onPressIn, onPressOut, disabled, pressedStyle, animate, animationDuration, animationLoop, animationEasing, animationDelay, autoPlay, onAnimationComplete, }: IconRendererProps): string | number | boolean | Iterable<React.ReactNode> | React.JSX.Element | null | undefined;
+export declare const IconRenderer: React.MemoExoticComponent<React.ForwardRefExoticComponent<IconRendererProps & React.RefAttributes<View>>>;
 //# sourceMappingURL=IconRenderer.d.ts.map

package/lib/typescript/babel/plugin.d.ts

@@ -9,6 +9,11 @@
  */
 import type { PluginObj, types as BabelTypes } from '@babel/core';
 import type { BabelPluginState } from './types';
+/**
+ * Reset all module-level build state
+ * Called when build completes or when stale build is detected
+ */
+declare function resetBuildState(): void;
 /**
  * Check if a scan lock file exists and is recent
  */
@@ -28,7 +33,7 @@ declare function releaseScanLock(lockPath: string): void;
 export declare function createRnIconifyPlugin(babel: {
     types: typeof BabelTypes;
 }): PluginObj<BabelPluginState>;
-export { acquireScanLock, releaseScanLock, isScanLockActive };
+export { acquireScanLock, releaseScanLock, isScanLockActive, resetBuildState };
 /**
  * Reset plugin state (for testing)
  */

package/lib/typescript/cache/CacheManager.d.ts

@@ -39,6 +39,12 @@ declare class CacheManagerImpl {
      * Guard to prevent reporting icons during bundle load
      */
     private isLoadingBundle;
+    /**
+     * Batched icon usage reports (DEV only)
+     * Accumulates icon names and flushes every 2 seconds
+     */
+    private pendingReports;
+    private reportTimer;
     /**
      * Initialize bundled icons from the Babel plugin cache
      * This should be called automatically on first access
@@ -135,9 +141,14 @@ declare class CacheManagerImpl {
     warmup(maxIcons?: number): void;
     /**
      * Report icon usage to Metro dev server (DEV only)
-     * Fire-and-forget POST to the Metro middleware
+     * Batches reports and flushes every 2 seconds to avoid
+     * flooding Metro with individual HTTP requests
      */
     reportIconUsage(iconName: string): void;
+    /**
+     * Flush batched icon usage reports to Metro dev server
+     */
+    private flushReports;
 }
 export declare const CacheManager: CacheManagerImpl;
 export {};

package/lib/typescript/cache/MemoryCache.d.ts

@@ -1,6 +1,8 @@
 /**
- * Simple in-memory cache for icon SVG data
- * Provides instant synchronous access to recently used icons
+ * LRU in-memory cache for icon SVG data
+ * Uses Map insertion-order trick for O(1) eviction:
+ * - get() deletes and re-inserts to move entry to tail
+ * - eviction removes from head (oldest) in O(1)
  */
 declare class MemoryCacheImpl {
     private cache;
@@ -8,11 +10,13 @@ declare class MemoryCacheImpl {
     constructor(maxSize?: number);
     /**
      * Get icon SVG from memory cache
+     * Moves the entry to the tail (most recently used)
      * @returns SVG string or null if not cached
      */
     get(iconName: string): string | null;
     /**
      * Store icon SVG in memory cache
+     * Evicts oldest entries if cache is at capacity
      */
     set(iconName: string, svg: string): void;
     /**
@@ -36,7 +40,8 @@ declare class MemoryCacheImpl {
      */
     keys(): string[];
     /**
-     * Evict the oldest entries to make room for new ones
+     * Evict the oldest 20% of entries
+     * O(1) per removal using Map's insertion order (head = oldest)
      */
     private evictOldest;
 }