react-native-debug-toolkit 0.6.4 → 2.1.0

package/src/features/NavigationLogFeature.ts

@@ -0,0 +1,44 @@
+import { NavigationLogTab } from '../components/NavigationLogTab';
+import type { DebugFeature, NavigationLogEntry } from '../types';
+import { createEventChannel } from '../utils/createEventChannel';
+import { createChannelFeature } from '../utils/createChannelFeature';
+
+type NavigationLogPayload = Omit<NavigationLogEntry, 'id'>;
+
+let navigationChannel = createEventChannel<NavigationLogPayload>();
+
+export const addNavigationLog = (
+  action: string,
+  from: string,
+  to: string,
+  startTime?: number,
+  duration?: number,
+  debugLog?: string,
+): void => {
+  navigationChannel.emit({
+    timestamp: Date.now(),
+    action,
+    from,
+    to,
+    startTime,
+    duration,
+    debugLog,
+  });
+};
+
+export interface NavigationFeatureConfig {
+  /** Maximum number of navigation logs to keep (default: 200) */
+  maxLogs?: number;
+}
+
+export const createNavigationLogFeature = (config?: NavigationFeatureConfig): DebugFeature<NavigationLogEntry> =>
+  createChannelFeature(
+    () => navigationChannel,
+    (payload, id) => ({ ...payload, id }),
+    { name: 'navigation', label: 'Navigation', renderContent: NavigationLogTab, maxLogs: config?.maxLogs },
+  );
+
+/** Reset module-level state for testing */
+export function _resetNavigationForTesting(): void {
+  navigationChannel = createEventChannel<NavigationLogPayload>();
+}

package/src/features/NetworkFeature.ts

@@ -0,0 +1,126 @@
+import { NetworkLogTab } from '../components/NetworkLogTab';
+import type { DebugFeature, NetworkLogEntry } from '../types';
+import { createEventChannel } from '../utils/createEventChannel';
+import { createObservableStore } from '../utils/createObservableStore';
+import { urlRewriter } from '../utils/urlRewriterRegistry';
+import {
+  startFetch,
+  startXMLHttpRequest,
+  setupAxios,
+  resetInterceptors,
+} from '../interceptors/networkInterceptor';
+import type { AxiosInstanceLike } from '../interceptors/networkInterceptor';
+
+type NetworkLogPayload = Omit<NetworkLogEntry, 'id'>;
+
+// ─── Utilities ────────────────────────────────────────
+
+function isUrlBlacklisted(
+  url: string,
+  blacklist: Array<string | RegExp>,
+): boolean {
+  if (!url) {
+    return false;
+  }
+  return blacklist.some((pattern) =>
+    pattern instanceof RegExp ? pattern.test(url) : url.includes(pattern),
+  );
+}
+
+// ─── Channel (shared pub-sub backbone) ─────────────────
+
+let networkChannel = createEventChannel<NetworkLogPayload>();
+
+function emitNetworkLog(entry: NetworkLogPayload): void {
+  networkChannel.emit(entry);
+}
+
+// ─── Feature factory ──────────────────────────────────
+
+const DEFAULT_MAX_LOGS = 200;
+
+export type { AxiosInstanceLike };
+
+export interface NetworkFeatureConfig {
+  /** Maximum number of network logs to keep (default: 200) */
+  maxLogs?: number;
+  /** URLs to filter out from logging */
+  blacklist?: Array<string | RegExp>;
+}
+
+export const createNetworkFeature = (config?: NetworkFeatureConfig): DebugFeature<NetworkLogEntry> & {
+  setupAxiosInterceptors: (axiosInstance: AxiosInstanceLike) => () => void;
+} => {
+  const maxLogs = config?.maxLogs ?? DEFAULT_MAX_LOGS;
+  const blacklist: Array<string | RegExp> = config?.blacklist ? [...config.blacklist] : [];
+  const logStore = createObservableStore<NetworkLogEntry>();
+  const axiosCleanupMap = new Map<AxiosInstanceLike, () => void>();
+
+  let nextId = 0;
+  let initialized = false;
+  let unsubscribeLogs: (() => void) | null = null;
+  let stopFetchFn: (() => void) | null = null;
+  let stopXMLHttpRequestFn: (() => void) | null = null;
+
+  const handleLog = (entry: NetworkLogPayload) => {
+    if (isUrlBlacklisted(entry.request.url, blacklist)) {
+      return;
+    }
+    logStore.push({ ...entry, id: String(nextId++) }, maxLogs);
+  };
+
+  return {
+    name: 'network',
+    label: 'Network',
+    renderContent: NetworkLogTab,
+    setup: () => {
+      if (initialized) {
+        return;
+      }
+      unsubscribeLogs = networkChannel.subscribe(handleLog);
+      stopFetchFn = startFetch(emitNetworkLog);
+      stopXMLHttpRequestFn = startXMLHttpRequest(emitNetworkLog);
+      initialized = true;
+    },
+    getData: () => logStore.getData(),
+    clear: () => {
+      logStore.clear();
+    },
+    cleanup: () => {
+      if (!initialized) {
+        return;
+      }
+      urlRewriter.set(null);
+      unsubscribeLogs?.();
+      unsubscribeLogs = null;
+      stopFetchFn?.();
+      stopFetchFn = null;
+      stopXMLHttpRequestFn?.();
+      stopXMLHttpRequestFn = null;
+      axiosCleanupMap.forEach((c) => c());
+      axiosCleanupMap.clear();
+      logStore.clear();
+      initialized = false;
+    },
+    subscribe: (listener) => logStore.subscribe(listener),
+    setupAxiosInterceptors: (axiosInstance) => {
+      const existingCleanup = axiosCleanupMap.get(axiosInstance);
+      if (existingCleanup) {
+        return existingCleanup;
+      }
+      const cleanup = setupAxios(axiosInstance, emitNetworkLog);
+      const trackedCleanup = () => {
+        cleanup();
+        axiosCleanupMap.delete(axiosInstance);
+      };
+      axiosCleanupMap.set(axiosInstance, trackedCleanup);
+      return trackedCleanup;
+    },
+  };
+};
+
+/** Reset module-level state for testing */
+export function _resetNetworkForTesting(): void {
+  networkChannel = createEventChannel<NetworkLogPayload>();
+  resetInterceptors();
+}

package/src/features/ThirdPartyLibsFeature.ts

@@ -0,0 +1,42 @@
+import { Platform } from 'react-native';
+import { ThirdPartyLibsTab } from '../components/ThirdPartyLibsTab';
+import { NativeDebugLibs } from '../native/NativeDebugLibs';
+import type { DebugFeature, ThirdPartyLib } from '../types';
+
+const availableLibs: ThirdPartyLib[] = [
+  {
+    id: 'flex',
+    name: 'FLEX',
+    description: 'In-app debugging and exploration tool for iOS',
+    platform: 'ios',
+    actions: [
+      { id: 'showExplorer', label: 'Show Explorer', onPress: NativeDebugLibs.showExplorer },
+      { id: 'hideExplorer', label: 'Hide Explorer', onPress: NativeDebugLibs.hideExplorer },
+    ],
+  },
+  {
+    id: 'doraemonkit',
+    name: 'DoraemonKit',
+    description: 'A full-featured iOS & Android development assistant',
+    platform: 'both',
+    actions: [
+      { id: 'showDoraemonKit', label: 'Show DoraemonKit', onPress: NativeDebugLibs.showDoraemonKit },
+      { id: 'hideDoraemonKit', label: 'Hide DoraemonKit', onPress: NativeDebugLibs.hideDoraemonKit },
+    ],
+  },
+];
+
+function getPlatformLibs(): ThirdPartyLib[] {
+  return availableLibs.filter(
+    (lib) => lib.platform === 'both' || lib.platform === Platform.OS,
+  );
+}
+
+export const createThirdPartyLibsFeature = (): DebugFeature<ThirdPartyLib> => ({
+  name: 'thirdPartyLibs',
+  label: 'Debug Libraries',
+  renderContent: ThirdPartyLibsTab,
+  setup: () => {},
+  getData: () => getPlatformLibs(),
+  cleanup: () => {},
+});

package/src/features/TrackFeature.ts

@@ -0,0 +1,34 @@
+import { TrackLogTab } from '../components/TrackLogTab';
+import type { DebugFeature, TrackLogEntry } from '../types';
+import { createEventChannel } from '../utils/createEventChannel';
+import { createChannelFeature } from '../utils/createChannelFeature';
+
+export interface TrackEventData {
+  eventName: string;
+  [key: string]: unknown;
+}
+
+type TrackLogPayload = TrackEventData & { timestamp: number };
+
+let trackChannel = createEventChannel<TrackLogPayload>();
+
+export const addTrackLog = (eventData: TrackEventData): void => {
+  trackChannel.emit({ timestamp: Date.now(), ...eventData });
+};
+
+export interface TrackFeatureConfig {
+  /** Maximum number of track events to keep (default: 200) */
+  maxLogs?: number;
+}
+
+export const createTrackFeature = (config?: TrackFeatureConfig): DebugFeature<TrackLogEntry> =>
+  createChannelFeature(
+    () => trackChannel,
+    (payload, id) => ({ ...payload, id }),
+    { name: 'track', label: 'Track', renderContent: TrackLogTab, maxLogs: config?.maxLogs },
+  );
+
+/** Reset module-level state for testing */
+export function _resetTrackForTesting(): void {
+  trackChannel = createEventChannel<TrackLogPayload>();
+}

package/src/features/ZustandLogFeature.ts

@@ -0,0 +1,101 @@
+import { ZustandLogTab } from '../components/ZustandLogTab';
+import type { DebugFeature, ZustandLogEntry } from '../types';
+import { createEventChannel } from '../utils/createEventChannel';
+import { createChannelFeature } from '../utils/createChannelFeature';
+
+type ZustandLogPayload = Omit<ZustandLogEntry, 'id'>;
+
+let zustandChannel = createEventChannel<ZustandLogPayload>();
+
+export const addZustandLog = (
+  action: string,
+  prevState: unknown,
+  nextState: unknown,
+  actionCompleteTime?: number,
+  storeName?: string,
+): void => {
+  zustandChannel.emit({
+    timestamp: Date.now(),
+    action,
+    prevState,
+    nextState,
+    actionCompleteTime,
+    storeName,
+  });
+};
+
+// ─── Zustand middleware (remains here — it's user-facing API) ──────────
+
+type ZustandSetState<T> = (
+  partial: T | Partial<T> | ((state: T) => Partial<T> | T),
+  replace?: boolean | undefined,
+  action?: string | { type: unknown } | undefined,
+) => void;
+
+type ZustandGetState<T> = () => T;
+
+interface ZustandStoreApi<T> {
+  getState: () => T;
+  setState: ZustandSetState<T>;
+  subscribe: (listener: (state: T, prevState: T) => void) => () => void;
+  name?: string;
+}
+
+type ZustandConfig<T> = (
+  set: ZustandSetState<T>,
+  get: ZustandGetState<T>,
+  api: ZustandStoreApi<T>,
+) => T;
+
+/**
+ * Zustand middleware that logs all state changes to the debug toolkit.
+ *
+ * Usage:
+ * ```ts
+ * const useStore = create(zustandLogMiddleware((set) => ({ ... })))
+ * ```
+ */
+export const zustandLogMiddleware = <T>(config: ZustandConfig<T>) => (
+  set: ZustandSetState<T>,
+  get: ZustandGetState<T>,
+  api: ZustandStoreApi<T>,
+) =>
+  config(
+    (args: Parameters<ZustandSetState<T>>[0], replace?: boolean, actionName?: string | { type: unknown }) => {
+      const prevState = get();
+      const startTime = Date.now();
+      set(args, replace, actionName);
+      const duration = Date.now() - startTime;
+      const label = typeof actionName === 'string'
+        ? actionName
+        : typeof args === 'function' ? 'setState' : 'object-set';
+      addZustandLog(
+        label,
+        prevState,
+        get(),
+        duration,
+        api.name,
+      );
+    },
+    get,
+    api,
+  );
+
+// ─── Feature factory ──────────────────────────────────────────────────
+
+export interface ZustandFeatureConfig {
+  /** Maximum number of zustand state changes to keep (default: 200) */
+  maxLogs?: number;
+}
+
+export const createZustandLogFeature = (config?: ZustandFeatureConfig): DebugFeature<ZustandLogEntry> =>
+  createChannelFeature(
+    () => zustandChannel,
+    (payload, id) => ({ ...payload, id }),
+    { name: 'zustand', label: 'Zustand', renderContent: ZustandLogTab, maxLogs: config?.maxLogs },
+  );
+
+/** Reset module-level state for testing */
+export function _resetZustandForTesting(): void {
+  zustandChannel = createEventChannel<ZustandLogPayload>();
+}

package/src/hooks/useNavigationLogger.ts

@@ -0,0 +1,102 @@
+import { useEffect, useRef } from 'react';
+import { addNavigationLog } from '../features/NavigationLogFeature';
+import { safeStringify } from '../utils/safeStringify';
+import type { NavigationContainerRef } from '../types';
+
+function getActiveRouteName(state: unknown): string {
+  let currentState = state as
+    | {
+        index?: number;
+        routes?: Array<{ name?: string; state?: unknown }>;
+      }
+    | undefined;
+
+  while (currentState?.routes && typeof currentState.index === 'number') {
+    const route = currentState.routes[currentState.index];
+    if (!route) {
+      return '';
+    }
+    if (!route.state) {
+      return route.name ?? '';
+    }
+    currentState = route.state as typeof currentState;
+  }
+
+  return '';
+}
+
+
+/**
+ * Hook to automatically log React Navigation events.
+ *
+ * Usage:
+ * ```tsx
+ * const navigationRef = useRef<NavigationContainerRef>(null);
+ * useNavigationLogger(navigationRef);
+ * return <NavigationContainer ref={navigationRef}>...</NavigationContainer>;
+ * ```
+ */
+export function useNavigationLogger(navigationRef: React.RefObject<NavigationContainerRef | null>) {
+  const previousRouteNameRef = useRef('');
+
+  useEffect(() => {
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+    let unsubscribe: (() => void) | undefined;
+    let disposed = false;
+
+    const attachListener = () => {
+      if (disposed) {
+        return;
+      }
+
+      const ref = navigationRef.current;
+      if (!ref || typeof ref.addListener !== 'function') {
+        timeoutId = setTimeout(attachListener, 250);
+        return;
+      }
+
+      const currentRouteName =
+        ref.getCurrentRoute?.()?.name ||
+        getActiveRouteName(ref.getRootState?.());
+      if (currentRouteName) {
+        previousRouteNameRef.current = currentRouteName;
+      }
+
+      unsubscribe = ref.addListener('state', () => {
+        try {
+          const navState = ref.getRootState?.();
+          const nextRouteName =
+            ref.getCurrentRoute?.()?.name ||
+            getActiveRouteName(navState);
+
+          if (!nextRouteName || nextRouteName === previousRouteNameRef.current) {
+            return;
+          }
+
+          addNavigationLog(
+            'navigate',
+            previousRouteNameRef.current,
+            nextRouteName,
+            undefined,
+            undefined,
+            safeStringify(navState),
+          );
+
+          previousRouteNameRef.current = nextRouteName;
+        } catch {
+          // Navigation state may not be ready
+        }
+      });
+    };
+
+    attachListener();
+
+    return () => {
+      disposed = true;
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+      unsubscribe?.();
+    };
+  }, [navigationRef]);
+}

package/src/hooks/useSlideDetailAnimation.ts

@@ -0,0 +1,45 @@
+import { useEffect, useRef } from 'react';
+import { Animated } from 'react-native';
+
+/**
+ * Shared slide-in/out animation for tab detail views.
+ * Returns animated styles for the detail overlay and the list behind it.
+ */
+export function useSlideDetailAnimation<T>(
+  selected: T | null,
+): {
+  detailTranslateX: Animated.AnimatedInterpolation<number>;
+  listTranslateX: Animated.AnimatedInterpolation<number>;
+  listOpacity: Animated.AnimatedInterpolation<number>;
+} {
+  const slideAnim = useRef(new Animated.Value(0)).current;
+  const listSlideAnim = useRef(new Animated.Value(0)).current;
+
+  useEffect(() => {
+    if (selected) {
+      listSlideAnim.setValue(0);
+      Animated.parallel([
+        Animated.spring(slideAnim, { toValue: 1, friction: 9, tension: 60, useNativeDriver: true }),
+        Animated.spring(listSlideAnim, { toValue: 1, friction: 9, tension: 60, useNativeDriver: true }),
+      ]).start();
+    } else {
+      slideAnim.setValue(0);
+      listSlideAnim.setValue(0);
+    }
+  }, [selected, slideAnim, listSlideAnim]);
+
+  const detailTranslateX = slideAnim.interpolate({
+    inputRange: [0, 1],
+    outputRange: [300, 0],
+  });
+  const listTranslateX = listSlideAnim.interpolate({
+    inputRange: [0, 1],
+    outputRange: [0, -60],
+  });
+  const listOpacity = listSlideAnim.interpolate({
+    inputRange: [0, 1],
+    outputRange: [1, 0],
+  });
+
+  return { detailTranslateX, listTranslateX, listOpacity };
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+// Core
+export { DebugToolkit } from './core/DebugToolkit';
+export { DebugToolkitProvider, useDebugToolkit } from './core/DebugToolkitProvider';
+export { DebugView } from './components/DebugView';
+export type { DebugViewProps } from './components/DebugView';
+export { initializeDebugToolkit } from './initialize';
+export type { InitializeOptions, FeatureConfigs } from './initialize';
+
+// Feature factories
+export { createNetworkFeature } from './features/NetworkFeature';
+export type { NetworkFeatureConfig, AxiosInstanceLike } from './features/NetworkFeature';
+export { createConsoleLogFeature } from './features/ConsoleLogFeature';
+export type { ConsoleFeatureConfig } from './features/ConsoleLogFeature';
+export { createZustandLogFeature, zustandLogMiddleware, addZustandLog } from './features/ZustandLogFeature';
+export type { ZustandFeatureConfig } from './features/ZustandLogFeature';
+export { createNavigationLogFeature, addNavigationLog } from './features/NavigationLogFeature';
+export type { NavigationFeatureConfig } from './features/NavigationLogFeature';
+export { createTrackFeature, addTrackLog } from './features/TrackFeature';
+export type { TrackFeatureConfig, TrackEventData } from './features/TrackFeature';
+export { createEnvironmentFeature } from './features/EnvironmentFeature';
+export type { EnvironmentFeatureAPI } from './features/EnvironmentFeature';
+export { createClipboardFeature } from './features/ClipboardFeature';
+
+// Hooks
+export { useNavigationLogger } from './hooks/useNavigationLogger';
+
+// Utilities
+export { safeStringify } from './utils/safeStringify';
+export { copyToComputer, logToComputer, fmt } from './utils/copyToComputer';
+export type { CopyResult, CopyOptions, CopyMethod } from './utils/copyToComputer';
+
+// Types
+export type {
+  AnyDebugFeature,
+  BuiltInFeatureName,
+  DebugFeature,
+  DebugFeatureRenderProps,
+  NetworkLogEntry,
+  ConsoleLogEntry,
+  ZustandLogEntry,
+  NavigationLogEntry,
+  TrackLogEntry,
+  EnvironmentConfig,
+  EnvironmentState,
+} from './types';
+
+// Default export for convenience
+export { initializeDebugToolkit as default } from './initialize';

package/src/initialize.ts

@@ -0,0 +1,122 @@
+import { DebugToolkit } from './core/DebugToolkit';
+import { createNetworkFeature } from './features/NetworkFeature';
+import type { NetworkFeatureConfig } from './features/NetworkFeature';
+import { createConsoleLogFeature } from './features/ConsoleLogFeature';
+import type { ConsoleFeatureConfig } from './features/ConsoleLogFeature';
+import { createZustandLogFeature } from './features/ZustandLogFeature';
+import type { ZustandFeatureConfig } from './features/ZustandLogFeature';
+import { createNavigationLogFeature } from './features/NavigationLogFeature';
+import type { NavigationFeatureConfig } from './features/NavigationLogFeature';
+import { createTrackFeature } from './features/TrackFeature';
+import type { TrackFeatureConfig } from './features/TrackFeature';
+import { createEnvironmentFeature } from './features/EnvironmentFeature';
+import { createClipboardFeature } from './features/ClipboardFeature';
+import type { AnyDebugFeature, BuiltInFeatureName } from './types';
+
+const isDebugMode = __DEV__;
+
+/** Feature-specific configuration map */
+export interface FeatureConfigs {
+  network?: boolean | NetworkFeatureConfig;
+  console?: boolean | ConsoleFeatureConfig;
+  zustand?: boolean | ZustandFeatureConfig;
+  navigation?: boolean | NavigationFeatureConfig;
+  track?: boolean | TrackFeatureConfig;
+  environment?: Parameters<typeof createEnvironmentFeature>[0];
+  clipboard?: boolean;
+}
+
+export interface InitializeOptions {
+  features?: FeatureConfigs;
+  enabled?: boolean;
+}
+
+/** Registry mapping feature names to creator functions */
+// Config param requires `any` — each factory accepts a different config type.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const featureRegistry: Record<BuiltInFeatureName, (config?: any) => AnyDebugFeature> = {
+  network: createNetworkFeature,
+  console: createConsoleLogFeature,
+  zustand: createZustandLogFeature,
+  navigation: createNavigationLogFeature,
+  track: createTrackFeature,
+  environment: createEnvironmentFeature,
+  clipboard: createClipboardFeature,
+};
+
+const DEFAULT_FEATURES: BuiltInFeatureName[] = [
+  'network',
+  'console',
+  'navigation',
+  'zustand',
+  'track',
+  'clipboard',
+];
+
+function resolveFeatureConfigs(configs: FeatureConfigs): AnyDebugFeature[] {
+  const features: AnyDebugFeature[] = [];
+  const entries = Object.entries(configs) as [BuiltInFeatureName, unknown][];
+
+  for (const [name, config] of entries) {
+    if (config === false) continue;
+
+    const creator = featureRegistry[name];
+    if (!creator) {
+      console.warn(`[DebugToolkit] Unknown feature: "${name}"`);
+      continue;
+    }
+
+    if (config === true || config === undefined) {
+      features.push(creator());
+    } else if (typeof config === 'object') {
+      features.push(creator(config as Record<string, unknown>));
+    }
+  }
+
+  return features;
+}
+
+function resolveDefaultFeatures(): AnyDebugFeature[] {
+  return DEFAULT_FEATURES.map((name) => featureRegistry[name]!());
+}
+
+/**
+ * Initialize the debug toolkit.
+ *
+ * @example
+ * initializeDebugToolkit({
+ *   features: { network: true, console: true },
+ *   enabled: true,
+ * });
+ */
+export function initializeDebugToolkit(
+  options?: InitializeOptions,
+): typeof DebugToolkit {
+  const enabled = options?.enabled ?? isDebugMode;
+
+  const resolvedFeatures = options?.features
+    ? resolveFeatureConfigs(options.features)
+    : resolveDefaultFeatures();
+
+  try {
+    DebugToolkit.setEnabled(enabled);
+
+    if (!enabled) {
+      DebugToolkit.reset();
+      return DebugToolkit;
+    }
+
+    DebugToolkit.replaceFeatures(resolvedFeatures);
+
+    if (DebugToolkit.hasFeatures()) {
+      DebugToolkit.showPanel();
+    } else {
+      DebugToolkit.hidePanel();
+    }
+
+    return DebugToolkit;
+  } catch (error) {
+    console.error('[DebugToolkit] Initialization failed:', error);
+    return DebugToolkit;
+  }
+}