react-native-prod-debugger 1.0.0

package/src/core/DebuggerProvider.tsx

@@ -0,0 +1,211 @@
+import React, { createContext, useState, useCallback, useEffect, useMemo, useRef } from 'react';
+import { View, StyleSheet } from 'react-native';
+import type { DebuggerConfig, DebuggerContextValue, DebuggerPlugin, ChildrenProp } from './types';
+import { createTheme } from './theme';
+import { PluginRegistry } from './PluginRegistry';
+import { DebugBubble } from './DebugBubble';
+import { DebugOverlay } from './DebugOverlay';
+import { GestureDetector } from './GestureDetector';
+
+// ─── Built-in Plugin Registrations ──────────────────────────────────────────
+import { createNetworkInspectorPlugin } from '../plugins/network/NetworkInspectorPlugin';
+import { createStateInspectorPlugin } from '../plugins/stateInspector/StateInspectorPlugin';
+import { createFeatureFlagsPlugin } from '../plugins/featureFlags/FeatureFlagsPlugin';
+import { createRemoteConfigPlugin } from '../plugins/remoteConfig/RemoteConfigPlugin';
+import { createConsoleViewerPlugin } from '../plugins/console/ConsoleViewerPlugin';
+import { createStorageBrowserPlugin } from '../plugins/storageBrowser/StorageBrowserPlugin';
+import { createPerformanceMonitorPlugin } from '../plugins/performance/PerformanceMonitorPlugin';
+import { createDeviceInfoPlugin } from '../plugins/deviceInfo/DeviceInfoPlugin';
+import { createNavigationInspectorPlugin } from '../plugins/navigationInspector/NavigationInspectorPlugin';
+import { createCrashReporterPlugin } from '../plugins/crashReporter/CrashReporterPlugin';
+import { createCustomActionsPlugin } from '../plugins/customActions/CustomActionsPlugin';
+import { createDeepLinkTesterPlugin } from '../plugins/deepLinkTester/DeepLinkTesterPlugin';
+import { createTimelinePlugin } from '../plugins/timeline/TimelinePlugin';
+
+// ─── Context ────────────────────────────────────────────────────────────────
+
+export const DebuggerContext = createContext<DebuggerContextValue | null>(null);
+
+// ─── Default Config ─────────────────────────────────────────────────────────
+
+const DEFAULT_CONFIG: Required<DebuggerConfig> = {
+  enabled: true,
+  gesture: 'threeFingerLongPress',
+  longPressDuration: 800,
+  numberOfFingers: 3,
+  interceptConsole: true,
+  interceptNetwork: true,
+  interceptCrashes: true,
+  maxNetworkRequests: 500,
+  maxConsoleEntries: 1000,
+  maxTimelineEvents: 2000,
+  appVersion: '',
+  buildNumber: '',
+  bundleId: '',
+  theme: {},
+  disabledPlugins: [],
+  bubblePosition: { x: -1, y: -1 },
+  bubbleSize: 50,
+};
+
+// ─── Provider ───────────────────────────────────────────────────────────────
+
+interface DebuggerProviderProps extends ChildrenProp {
+  config?: DebuggerConfig;
+}
+
+/**
+ * DebuggerProvider — Wrap your app with this to enable the production debugger.
+ *
+ * @example
+ * ```tsx
+ * import { DebuggerProvider } from 'react-native-prod-debugger';
+ *
+ * export default function App() {
+ *   return (
+ *     <DebuggerProvider config={{ appVersion: '1.2.3' }}>
+ *       <YourApp />
+ *     </DebuggerProvider>
+ *   );
+ * }
+ * ```
+ */
+export const DebuggerProvider: React.FC<DebuggerProviderProps> = ({
+  children,
+  config: userConfig,
+}) => {
+  const mergedConfig = useMemo<Required<DebuggerConfig>>(
+    () => ({
+      ...DEFAULT_CONFIG,
+      ...userConfig,
+      theme: { ...DEFAULT_CONFIG.theme, ...(userConfig?.theme || {}) },
+    }),
+    [userConfig],
+  );
+
+  const theme = useMemo(() => createTheme(mergedConfig.theme), [mergedConfig.theme]);
+
+  const [isVisible, setIsVisible] = useState(false);
+  const [showOverlay, setShowOverlay] = useState(false);
+  const [plugins, setPlugins] = useState<DebuggerPlugin[]>([]);
+  const initialized = useRef(false);
+
+  // Register built-in plugins on mount
+  useEffect(() => {
+    if (!mergedConfig.enabled || initialized.current) return;
+    initialized.current = true;
+
+    const disabled = new Set(mergedConfig.disabledPlugins);
+
+    const builtInPlugins = [
+      createNetworkInspectorPlugin(),
+      createConsoleViewerPlugin(),
+      createStateInspectorPlugin(),
+      createFeatureFlagsPlugin(),
+      createRemoteConfigPlugin(),
+      createStorageBrowserPlugin(),
+      createPerformanceMonitorPlugin(),
+      createDeviceInfoPlugin(),
+      createNavigationInspectorPlugin(),
+      createCrashReporterPlugin(),
+      createCustomActionsPlugin(),
+      createDeepLinkTesterPlugin(),
+      createTimelinePlugin(),
+    ];
+
+    for (const plugin of builtInPlugins) {
+      if (!disabled.has(plugin.id)) {
+        PluginRegistry.register(plugin);
+      }
+    }
+
+    PluginRegistry.initAll();
+    setPlugins(PluginRegistry.getAll());
+
+    // Subscribe to registry changes (for custom plugins added later)
+    const unsubscribe = PluginRegistry.subscribe(() => {
+      setPlugins(PluginRegistry.getAll());
+    });
+
+    return () => {
+      unsubscribe();
+      PluginRegistry.destroyAll();
+    };
+  }, [mergedConfig.enabled, mergedConfig.disabledPlugins]);
+
+  const show = useCallback(() => {
+    setIsVisible(true);
+    setShowOverlay(false);
+  }, []);
+
+  const hide = useCallback(() => {
+    setIsVisible(false);
+    setShowOverlay(false);
+  }, []);
+
+  const toggle = useCallback(() => {
+    setIsVisible((prev) => !prev);
+    setShowOverlay(false);
+  }, []);
+
+  const handleBubblePress = useCallback(() => {
+    setShowOverlay(true);
+  }, []);
+
+  const handleOverlayClose = useCallback(() => {
+    setShowOverlay(false);
+  }, []);
+
+  const contextValue = useMemo<DebuggerContextValue>(
+    () => ({
+      isVisible,
+      toggle,
+      show,
+      hide,
+      config: mergedConfig,
+      theme,
+      plugins,
+    }),
+    [isVisible, toggle, show, hide, mergedConfig, theme, plugins],
+  );
+
+  if (!mergedConfig.enabled) {
+    return <>{children}</>;
+  }
+
+  return (
+    <DebuggerContext.Provider value={contextValue}>
+      <View style={styles.root}>
+        <GestureDetector
+          gesture={mergedConfig.gesture}
+          numberOfFingers={mergedConfig.numberOfFingers}
+          longPressDuration={mergedConfig.longPressDuration}
+          onActivate={toggle}
+        >
+          {children}
+        </GestureDetector>
+
+        {isVisible && !showOverlay && (
+          <DebugBubble
+            onPress={handleBubblePress}
+            theme={theme}
+            size={mergedConfig.bubbleSize}
+            initialPosition={
+              mergedConfig.bubblePosition.x >= 0 ? mergedConfig.bubblePosition : undefined
+            }
+          />
+        )}
+
+        {isVisible && showOverlay && (
+          <DebugOverlay plugins={plugins} theme={theme} onClose={handleOverlayClose} />
+        )}
+      </View>
+    </DebuggerContext.Provider>
+  );
+};
+
+const styles = StyleSheet.create({
+  root: {
+    flex: 1,
+  },
+});

package/src/core/GestureDetector.tsx

@@ -0,0 +1,95 @@
+import React, { useRef, useCallback } from 'react';
+import { View, StyleSheet } from 'react-native';
+import type { GestureType, ChildrenProp } from './types';
+
+interface GestureDetectorProps extends ChildrenProp {
+  gesture: GestureType;
+  numberOfFingers: number;
+  longPressDuration: number;
+  onActivate: () => void;
+}
+
+/**
+ * GestureDetector — Invisible wrapper that detects multi-touch gestures.
+ *
+ * Supported gestures:
+ * - `threeFingerLongPress`: N fingers held down for duration ms
+ * - `twoFingerTripleTap`: 2 fingers tapped 3 times quickly
+ * - `shake`: (detected elsewhere — React Native DevMenu shim)
+ * - `custom`: (no built-in behavior — consumers control programmatically)
+ */
+export const GestureDetector: React.FC<GestureDetectorProps> = ({
+  children,
+  gesture,
+  numberOfFingers,
+  longPressDuration,
+  onActivate,
+}) => {
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const tapCountRef = useRef(0);
+  const tapTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const clearTimer = useCallback(() => {
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+  }, []);
+
+  const handleTouchStart = useCallback(
+    (event: { nativeEvent: { touches: unknown[] } }) => {
+      const touchCount = event.nativeEvent.touches?.length ?? 0;
+
+      if (gesture === 'threeFingerLongPress') {
+        if (touchCount >= numberOfFingers) {
+          clearTimer();
+          timerRef.current = setTimeout(() => {
+            onActivate();
+          }, longPressDuration);
+        }
+      }
+
+      if (gesture === 'twoFingerTripleTap') {
+        if (touchCount >= 2) {
+          tapCountRef.current += 1;
+
+          if (tapTimerRef.current) clearTimeout(tapTimerRef.current);
+          tapTimerRef.current = setTimeout(() => {
+            tapCountRef.current = 0;
+          }, 600); // Reset tap count after 600ms idle
+
+          if (tapCountRef.current >= 3) {
+            tapCountRef.current = 0;
+            onActivate();
+          }
+        }
+      }
+    },
+    [gesture, numberOfFingers, longPressDuration, onActivate, clearTimer],
+  );
+
+  const handleTouchEnd = useCallback(() => {
+    if (gesture === 'threeFingerLongPress') {
+      clearTimer();
+    }
+  }, [gesture, clearTimer]);
+
+  if (gesture === 'custom' || gesture === 'shake') {
+    return <View style={styles.flex}>{children}</View>;
+  }
+
+  return (
+    <View
+      style={styles.flex}
+      onTouchStart={handleTouchStart}
+      onTouchEnd={handleTouchEnd}
+      onTouchCancel={handleTouchEnd}
+    >
+      {children}
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  flex: { flex: 1 },
+});

package/src/core/PluginRegistry.ts

@@ -0,0 +1,118 @@
+import type { DebuggerPlugin } from './types';
+
+/**
+ * PluginRegistry — Central registry for all debugger plugins.
+ *
+ * Plugins are stored in a static array and sorted by their `order` property.
+ * Built-in plugins are registered automatically by DebuggerProvider.
+ * Custom plugins can be registered by consumers at any time.
+ */
+class PluginRegistryClass {
+  private plugins: Map<string, DebuggerPlugin> = new Map();
+  private listeners: Set<() => void> = new Set();
+
+  /** Register a plugin. Replaces existing plugin with the same ID. */
+  register(plugin: DebuggerPlugin): void {
+    this.plugins.set(plugin.id, {
+      ...plugin,
+      order: plugin.order ?? 100,
+    });
+    this.notify();
+  }
+
+  /** Unregister a plugin by ID. */
+  unregister(id: string): void {
+    const plugin = this.plugins.get(id);
+    if (plugin?.onDestroy) {
+      try {
+        plugin.onDestroy();
+      } catch {
+        // Silently handle cleanup errors
+      }
+    }
+    this.plugins.delete(id);
+    this.notify();
+  }
+
+  /** Get all registered plugins, sorted by order. */
+  getAll(): DebuggerPlugin[] {
+    return Array.from(this.plugins.values()).sort((a, b) => (a.order ?? 100) - (b.order ?? 100));
+  }
+
+  /** Get a plugin by ID. */
+  get(id: string): DebuggerPlugin | undefined {
+    return this.plugins.get(id);
+  }
+
+  /** Check if a plugin is registered. */
+  has(id: string): boolean {
+    return this.plugins.has(id);
+  }
+
+  /** Get the count of registered plugins. */
+  get count(): number {
+    return this.plugins.size;
+  }
+
+  /** Subscribe to registry changes. Returns unsubscribe function. */
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  /** Initialize all plugins (called by DebuggerProvider on mount). */
+  initAll(): void {
+    for (const plugin of this.plugins.values()) {
+      if (plugin.onInit) {
+        try {
+          plugin.onInit();
+        } catch (error) {
+          console.warn(`[ProdDebugger] Plugin "${plugin.id}" init failed:`, error);
+        }
+      }
+    }
+  }
+
+  /** Destroy all plugins (called by DebuggerProvider on unmount). */
+  destroyAll(): void {
+    for (const plugin of this.plugins.values()) {
+      if (plugin.onDestroy) {
+        try {
+          plugin.onDestroy();
+        } catch {
+          // Silently handle cleanup errors
+        }
+      }
+    }
+  }
+
+  /** Clear all plugins from the registry. */
+  clear(): void {
+    this.destroyAll();
+    this.plugins.clear();
+    this.notify();
+  }
+
+  private notify(): void {
+    for (const listener of this.listeners) {
+      try {
+        listener();
+      } catch {
+        // Silently handle listener errors
+      }
+    }
+  }
+}
+
+/** Singleton plugin registry instance. */
+export const PluginRegistry = new PluginRegistryClass();
+
+/** Register a custom plugin. Convenience function. */
+export function registerPlugin(plugin: DebuggerPlugin): void {
+  PluginRegistry.register(plugin);
+}
+
+/** Unregister a plugin by ID. Convenience function. */
+export function unregisterPlugin(id: string): void {
+  PluginRegistry.unregister(id);
+}

package/src/core/theme.ts

@@ -0,0 +1,41 @@
+import type { DebuggerTheme } from './types';
+
+/**
+ * Default dark theme — designed for optimal readability on top of any app UI.
+ * High-contrast text, muted backgrounds with alpha transparency for the overlay.
+ */
+export const darkTheme: DebuggerTheme = {
+  background: '#0D0D0D',
+  surface: '#1A1A2E',
+  surfaceAlt: '#16213E',
+  text: '#EAEAEA',
+  textSecondary: '#A0A0B0',
+  textMuted: '#6B6B80',
+  accent: '#7C3AED',
+  accentLight: '#A78BFA',
+  success: '#10B981',
+  warning: '#F59E0B',
+  error: '#EF4444',
+  info: '#3B82F6',
+  border: '#2A2A3E',
+  overlay: 'rgba(0, 0, 0, 0.85)',
+  bubbleBackground: '#7C3AED',
+  bubbleIcon: '#FFFFFF',
+  codeBackground: '#111122',
+  codeText: '#A5D6FF',
+  headerBackground: '#0F0F23',
+  tabActive: '#7C3AED',
+  tabInactive: '#4A4A5E',
+  statusBarOk: '#10B981',
+  statusBarWarn: '#F59E0B',
+  statusBarError: '#EF4444',
+  shadow: 'rgba(0, 0, 0, 0.5)',
+};
+
+/**
+ * Merge user theme overrides with the default dark theme.
+ */
+export function createTheme(overrides?: Partial<DebuggerTheme>): DebuggerTheme {
+  if (!overrides) return darkTheme;
+  return { ...darkTheme, ...overrides };
+}