@buoy-gg/highlight-updates 2.0.2

package/lib/typescript/highlight-updates/utils/PerformanceLogger.d.ts

@@ -0,0 +1,135 @@
+/**
+ * PerformanceLogger
+ *
+ * Dedicated performance measurement utility for the Highlight Updates feature.
+ * Tracks timing metrics across the render detection pipeline to identify bottlenecks
+ * and measure optimization improvements.
+ *
+ * Usage:
+ *   PerformanceLogger.setEnabled(true);  // Enable logging
+ *   const batch = PerformanceLogger.startBatch(nodesReceived);
+ *   batch.markFilteringComplete(nodesFiltered, nodesToProcess);
+ *   batch.markMeasurementComplete(successCount, failCount);
+ *   batch.markTrackingComplete();
+ *   batch.markCallbackComplete();
+ *   batch.finish();  // Logs the complete metrics
+ */
+export interface BatchMetrics {
+    batchId: string;
+    timestamp: number;
+    nodesReceived: number;
+    nodesFiltered: number;
+    nodesToProcess: number;
+    batchSize: number;
+    nodesInBatch: number;
+    filteringTime: number;
+    measurementTime: number;
+    trackingTime: number;
+    callbackTime: number;
+    totalTime: number;
+    measurementSuccessCount: number;
+    measurementFailCount: number;
+    overlayRenderTime?: number;
+}
+/**
+ * Call this when a traceUpdates event is received to track end-to-end latency
+ */
+export declare function markEventReceived(): number;
+/**
+ * Call this from the overlay when highlights are actually rendered
+ */
+export declare function markOverlayRendered(highlightCount: number, renderTime?: number): void;
+export interface BatchTimer {
+    markFilteringComplete: (nodesFiltered: number, nodesToProcess: number) => void;
+    markMeasurementStart: () => void;
+    markMeasurementComplete: (successCount: number, failCount: number) => void;
+    markTrackingComplete: () => void;
+    markCallbackComplete: () => void;
+    setOverlayRenderTime: (timeMs: number) => void;
+    finish: () => BatchMetrics;
+    getBatchId: () => string;
+}
+type MetricsListener = (metrics: BatchMetrics) => void;
+interface RollingStats {
+    batchCount: number;
+    totalNodes: number;
+    totalFiltered: number;
+    totalProcessed: number;
+    totalTime: number;
+    maxTime: number;
+    minTime: number;
+    avgMeasurementTime: number;
+}
+declare class PerformanceLoggerSingleton {
+    private enabled;
+    private batchCounter;
+    private listeners;
+    private rollingStats;
+    private recentBatches;
+    private readonly MAX_HISTORY;
+    private summaryInterval;
+    private readonly SUMMARY_INTERVAL_MS;
+    /**
+     * Enable or disable performance logging
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Check if logging is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Start timing a new batch of render updates
+     */
+    startBatch(nodesReceived: number, batchSize: number): BatchTimer;
+    /**
+     * Record metrics and log them
+     */
+    private recordMetrics;
+    /**
+     * Log a single batch's metrics
+     */
+    private logBatch;
+    /**
+     * Log periodic summary stats
+     */
+    private logSummary;
+    /**
+     * Reset rolling statistics
+     */
+    private resetStats;
+    /**
+     * Start the summary logging interval
+     */
+    private startSummaryInterval;
+    /**
+     * Stop the summary logging interval
+     */
+    private stopSummaryInterval;
+    /**
+     * Subscribe to metrics updates
+     */
+    subscribe(listener: MetricsListener): () => void;
+    /**
+     * Notify all listeners of new metrics
+     */
+    private notifyListeners;
+    /**
+     * Get recent batch history
+     */
+    getRecentBatches(): BatchMetrics[];
+    /**
+     * Get current rolling stats
+     */
+    getRollingStats(): RollingStats;
+    /**
+     * Clear all history and stats
+     */
+    clear(): void;
+    /**
+     * Generate a detailed report of recent performance
+     */
+    generateReport(): string;
+}
+export declare const PerformanceLogger: PerformanceLoggerSingleton;
+export default PerformanceLogger;
+//# sourceMappingURL=PerformanceLogger.d.ts.map

package/lib/typescript/highlight-updates/utils/ProfilerInterceptor.d.ts

@@ -0,0 +1,91 @@
+/**
+ * ProfilerInterceptor
+ *
+ * Swizzles React DevTools internals to capture and log exactly what the
+ * profiler detects when "Highlight updates when components render" is enabled.
+ *
+ * This allows us to compare profiler detection with our own implementation
+ * to ensure 100% accuracy.
+ *
+ * Usage:
+ *   import { installProfilerInterceptor } from './ProfilerInterceptor';
+ *   installProfilerInterceptor();
+ */
+/**
+ * Log information about available renderer interfaces.
+ * Only call this manually for debugging - not called during normal operation.
+ * @internal
+ */
+export declare function logRendererInterfaces(): void;
+/**
+ * Log hook structure for debugging.
+ * Only call this manually for debugging - not called during normal operation.
+ * @internal
+ */
+export declare function logHookStructure(): void;
+/**
+ * Enable trace updates on all renderer interfaces
+ *
+ * This is what DevTools does when you check "Highlight updates when components render"
+ *
+ * Reference: backend.js line 15487-15489
+ *   function setTraceUpdatesEnabled(isEnabled) {
+ *     traceUpdatesEnabled = isEnabled;
+ *   }
+ */
+declare function enableTracingOnAllRenderers(): void;
+/**
+ * Disable trace updates on all renderer interfaces
+ */
+declare function disableTracingOnAllRenderers(): void;
+/**
+ * Set a callback to receive profiler nodes for comparison
+ */
+export declare function setComparisonCallback(callback: ((nodes: Set<unknown>) => void) | null): void;
+/**
+ * Install all profiler interception hooks
+ *
+ * Call this early in your app initialization to capture all events.
+ * Installation is silent - no console logs in normal operation.
+ */
+export declare function installProfilerInterceptor(): void;
+/**
+ * Uninstall profiler interception hooks and restore original functions
+ */
+export declare function uninstallProfilerInterceptor(): void;
+/**
+ * Check if interceptor is currently installed
+ */
+export declare function isInterceptorInstalled(): boolean;
+/**
+ * Enable profiler logging - starts logging all profiler events
+ *
+ * NOTE: This only enables LOGGING of events. It does NOT enable tracing.
+ * The profiler must be enabled separately (e.g., via Chrome DevTools checkbox)
+ * for events to be emitted. This allows us to compare what the real profiler
+ * detects without our code interfering.
+ */
+export declare function enableProfilerLogging(): void;
+/**
+ * Disable profiler logging - stops logging profiler events
+ * NOTE: Does NOT disable tracing - the profiler continues to work,
+ * we just stop logging its events
+ */
+export declare function disableProfilerLogging(): void;
+/**
+ * Check if logging is currently enabled
+ */
+export declare function isLoggingEnabled(): boolean;
+declare const _default: {
+    install: typeof installProfilerInterceptor;
+    uninstall: typeof uninstallProfilerInterceptor;
+    isInstalled: typeof isInterceptorInstalled;
+    setComparisonCallback: typeof setComparisonCallback;
+    enableTracing: typeof enableTracingOnAllRenderers;
+    disableTracing: typeof disableTracingOnAllRenderers;
+    enableLogging: typeof enableProfilerLogging;
+    disableLogging: typeof disableProfilerLogging;
+    isLoggingEnabled: typeof isLoggingEnabled;
+};
+export default _default;
+//# sourceMappingURL=ProfilerInterceptor.d.ts.map

package/lib/typescript/highlight-updates/utils/RenderCauseDetector.d.ts

@@ -0,0 +1,68 @@
+/**
+ * RenderCauseDetector
+ *
+ * Detects WHY a component rendered by comparing current fiber state
+ * to previously stored state. Supports detection of:
+ * - First mount
+ * - Props changes (with changed key names)
+ * - Hooks/state changes (with hook indices)
+ * - Parent re-renders
+ *
+ * TWO-LEVEL CAUSATION:
+ * 1. Native level: Why did the native view's props change? (style, accessibilityState, etc.)
+ * 2. Component level: Why did the owning React component re-render? (props, state, parent)
+ *
+ * This gives the full picture:
+ * "StepperValueDisplay re-rendered because PARENT, which caused native Text to update PROPS [style]"
+ *
+ * COMPONENT-SPECIFIC DETECTION:
+ * Different native components have different important props:
+ * - RCTText: `children` IS the text content - always track it
+ * - RCTView: `children` is React elements - skip it
+ * - RCTImageView: `source` is the image URL - track it
+ *
+ * See: RENDER_CAUSE_TEXT_COMPONENT_PLAN.md for full documentation
+ */
+import type { RenderCause, DebugLogLevel } from "./RenderTracker";
+/**
+ * Detect why a component rendered
+ *
+ * @param nativeTag - The native tag of the component
+ * @param fiber - The React fiber object (host fiber)
+ * @param batchNativeTags - Set of all nativeTags in this render batch (for parent detection)
+ * @param debugLogLevel - Debug logging level: "off" | "minimal" | "verbose" | "all"
+ * @returns RenderCause object describing why the component rendered
+ */
+export declare function detectRenderCause(nativeTag: number, fiber: any, batchNativeTags: Set<number>, debugLogLevel?: DebugLogLevel): RenderCause;
+/**
+ * Clear all stored states
+ * Call this when tracking is disabled to prevent memory leaks
+ */
+export declare function clearRenderCauseState(): void;
+/**
+ * Remove a specific component from state storage
+ * Useful when a component is unmounted
+ */
+export declare function removeRenderCauseState(nativeTag: number): void;
+/**
+ * Get storage stats for debugging/display
+ */
+export declare function getRenderCauseStats(): {
+    storedStates: number;
+    maxStates: number;
+};
+/**
+ * Safely clone props/state for history storage.
+ * Handles circular references, functions, and large objects.
+ */
+export declare function safeCloneForHistory(value: any, depth?: number, seen?: WeakSet<object>): any;
+/**
+ * Capture props snapshot from a fiber for history storage
+ */
+export declare function capturePropsSnapshot(fiber: any): Record<string, any> | undefined;
+/**
+ * Capture state snapshot from a fiber for history storage
+ * For function components, this walks the hooks linked list
+ */
+export declare function captureStateSnapshot(fiber: any): any;
+//# sourceMappingURL=RenderCauseDetector.d.ts.map

package/lib/typescript/highlight-updates/utils/RenderTracker.d.ts

@@ -0,0 +1,407 @@
+/**
+ * RenderTracker
+ *
+ * Singleton that tracks component render history for the Highlight Updates modal.
+ * Stores information about each tracked component including render counts,
+ * timestamps, and identifying props (testID, nativeID, etc.)
+ */
+/**
+ * Debug logging levels for render cause detection.
+ * Controls verbosity of console output for debugging "Why Did You Render" feature.
+ *
+ * - "off": No debug logging (default, best for production)
+ * - "minimal": Only log state/hook value changes (e.g., "useState: 3334 → 3335")
+ * - "verbose": Log component info + cause + value changes
+ * - "all": Full fiber dump with everything (native fiber, component fiber, hooks, batch context)
+ */
+export type DebugLogLevel = "off" | "minimal" | "verbose" | "all";
+export type RenderCauseType = "mount" | "props" | "state" | "hooks" | "context" | "parent" | "unknown";
+export type ComponentCauseType = "mount" | "props" | "state" | "parent" | "unknown";
+/**
+ * Represents a change in a single hook's state
+ * Used to show meaningful before/after values for debugging
+ */
+export interface HookStateChange {
+    /** Hook index in the linked list (0-based) */
+    index: number;
+    /** Detected hook type */
+    type: 'useState' | 'useReducer' | 'useRef' | 'useMemo' | 'useCallback' | 'useEffect' | 'unknown';
+    /** Previous value (if available) */
+    previousValue?: any;
+    /** Current value */
+    currentValue?: any;
+    /** Human-readable description of the change */
+    description?: string;
+}
+export interface RenderCause {
+    type: RenderCauseType;
+    changedKeys?: string[];
+    hookIndices?: number[];
+    /** Detailed hook state changes with actual values (Phase 3 enhancement) */
+    hookChanges?: HookStateChange[];
+    timestamp: number;
+    componentCause?: ComponentCauseType;
+    componentName?: string;
+}
+/**
+ * A single render event in the history
+ * Captures everything about one render occurrence
+ */
+export interface RenderEvent {
+    id: string;
+    timestamp: number;
+    cause: RenderCause;
+    capturedProps?: Record<string, any>;
+    capturedState?: any;
+    renderNumber: number;
+}
+export interface TrackedRender {
+    id: string;
+    nativeTag: number;
+    viewType: string;
+    displayName: string;
+    testID?: string;
+    nativeID?: string;
+    accessibilityLabel?: string;
+    componentName?: string;
+    renderCount: number;
+    firstRenderTime: number;
+    lastRenderTime: number;
+    measurements?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    color: string;
+    lastRenderCause?: RenderCause;
+    renderHistory?: RenderEvent[];
+}
+export type FilterType = "any" | "viewType" | "testID" | "nativeID" | "component" | "accessibilityLabel";
+export interface FilterPattern {
+    type: FilterType;
+    value: string;
+}
+export interface FilterConfig {
+    includeTestID: Set<string>;
+    includeNativeID: Set<string>;
+    includeViewType: Set<string>;
+    includeComponent: Set<string>;
+    excludeTestID: Set<string>;
+    excludeNativeID: Set<string>;
+    excludeViewType: Set<string>;
+    excludeComponent: Set<string>;
+    includePatterns: FilterPattern[];
+    excludePatterns: FilterPattern[];
+    minRenderCount?: number;
+    maxRenderCount?: number;
+}
+type RenderTrackerListener = (renders: TrackedRender[]) => void;
+type StateListener = (state: {
+    isTracking: boolean;
+    isPaused: boolean;
+}) => void;
+type SettingsListener = (settings: RenderTrackerSettings) => void;
+type FilterListener = (filters: FilterConfig) => void;
+export interface RenderTrackerSettings {
+    /**
+     * Maximum number of components to highlight per batch.
+     * Higher values show more highlights but may impact performance.
+     * Range: 10-500, Default: 150
+     */
+    batchSize: number;
+    /**
+     * Whether to show and track render counts on highlight badges.
+     * Disabling this improves performance by skipping count tracking.
+     * Default: true
+     */
+    showRenderCount: boolean;
+    /**
+     * Whether to enable performance logging to the console.
+     * Logs detailed timing metrics for each batch of highlights.
+     * Useful for debugging and optimization.
+     * Default: false
+     */
+    performanceLogging: boolean;
+    /**
+     * Whether to track and display render causes (why components rendered).
+     * Detects props changes, hooks changes, parent re-renders, and first mounts.
+     * Adds ~2-5% performance overhead and stores previous component state in memory.
+     * Requires showRenderCount to be enabled.
+     * Default: false
+     */
+    trackRenderCauses: boolean;
+    /**
+     * Whether to enable render history tracking.
+     * When enabled, stores a history of render events per component for
+     * event stepping and diff visualization. Has memory and performance overhead.
+     * Requires trackRenderCauses to be enabled.
+     * Default: false
+     */
+    enableRenderHistory: boolean;
+    /**
+     * Maximum number of render events to store per component.
+     * Older events are discarded when this limit is reached.
+     * Range: 5-50, Default: 20
+     */
+    maxRenderHistoryPerComponent: number;
+    /**
+     * Whether to capture props at each render for diff visualization.
+     * Enabling this allows comparing props between renders but increases
+     * memory usage significantly. Only effective when enableRenderHistory is true.
+     * Default: false
+     */
+    capturePropsOnRender: boolean;
+    /**
+     * Whether to capture state at each render for diff visualization.
+     * Enabling this allows comparing state between renders but increases
+     * memory usage. Only effective when enableRenderHistory is true.
+     * Default: false
+     */
+    captureStateOnRender: boolean;
+    /**
+     * Debug logging level for render cause detection.
+     * Controls console output verbosity for "Why Did You Render" debugging.
+     *
+     * - "off": No debug logging (default)
+     * - "minimal": Only state/hook value changes (e.g., "useState: 3334 → 3335")
+     * - "verbose": Component info + cause + value changes
+     * - "all": Full fiber dump with everything
+     *
+     * Default: "off"
+     */
+    debugLogLevel: DebugLogLevel;
+    /**
+     * @deprecated Use debugLogLevel instead. Kept for backward compatibility.
+     * When true, equivalent to debugLogLevel: "all"
+     */
+    debugRawFiberLogging: boolean;
+}
+declare class RenderTrackerSingleton {
+    private renders;
+    private listeners;
+    private stateListeners;
+    private settingsListeners;
+    private filterListeners;
+    private isTracking;
+    private isPaused;
+    private settings;
+    private isBatchMode;
+    private batchDirty;
+    private filters;
+    /**
+     * Track a component render
+     */
+    trackRender(data: {
+        nativeTag: number;
+        viewType: string;
+        testID?: string;
+        nativeID?: string;
+        accessibilityLabel?: string;
+        componentName?: string;
+        measurements?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        color: string;
+        count: number;
+        renderCause?: RenderCause;
+        capturedProps?: Record<string, any>;
+        capturedState?: any;
+    }): void;
+    /**
+     * Add a render event to a component's history (circular buffer)
+     */
+    private addRenderEvent;
+    /**
+     * Start batch mode - defers listener notifications until endBatch() is called.
+     * Use this when tracking multiple renders in a loop to avoid O(n²) notifications.
+     */
+    startBatch(): void;
+    /**
+     * End batch mode and notify listeners if any renders were tracked.
+     */
+    endBatch(): void;
+    /**
+     * Get all tracked renders
+     * Creates new object copies to trigger React.memo re-renders
+     */
+    getRenders(): TrackedRender[];
+    /**
+     * Check if a component passes all active filters.
+     * Used by both the modal list and the overlay to filter components.
+     *
+     * @param info Component info to check (can be TrackedRender or extracted component info)
+     * @returns true if the component passes all filters, false if it should be hidden
+     */
+    passesFilters(info: {
+        viewType: string;
+        displayName?: string;
+        testID?: string;
+        nativeID?: string;
+        accessibilityLabel?: string;
+        componentName?: string;
+    }): boolean;
+    /**
+     * Check if component info matches any of the given patterns
+     */
+    private matchesAnyPatternForInfo;
+    /**
+     * Check if any filters are currently active
+     */
+    hasActiveFilters(): boolean;
+    /**
+     * Get filtered renders based on current filter config
+     */
+    getFilteredRenders(searchText?: string): TrackedRender[];
+    /**
+     * Check if a value matches any pattern in the set
+     */
+    private matchesPattern;
+    /**
+     * Get a single render by id
+     */
+    getRender(id: string): TrackedRender | undefined;
+    /**
+     * Clear all tracked renders
+     */
+    clear(): void;
+    /**
+     * Reset render count for a specific component
+     */
+    resetRenderCount(id: string): void;
+    /**
+     * Start tracking
+     */
+    start(): void;
+    /**
+     * Stop tracking
+     */
+    stop(): void;
+    /**
+     * Pause tracking (keeps state but stops adding new renders)
+     */
+    pause(): void;
+    /**
+     * Resume tracking
+     */
+    resume(): void;
+    /**
+     * Toggle pause state
+     */
+    togglePause(): void;
+    /**
+     * Get current tracking state
+     */
+    getState(): {
+        isTracking: boolean;
+        isPaused: boolean;
+    };
+    /**
+     * Get filter config
+     */
+    getFilters(): FilterConfig;
+    /**
+     * Update filter config
+     */
+    setFilters(filters: Partial<FilterConfig>): void;
+    /**
+     * Add an include pattern
+     */
+    addIncludePattern(type: "testID" | "nativeID" | "viewType" | "component", pattern: string): void;
+    /**
+     * Remove an include pattern
+     */
+    removeIncludePattern(type: "testID" | "nativeID" | "viewType" | "component", pattern: string): void;
+    /**
+     * Add an exclude pattern
+     */
+    addExcludePattern(type: "testID" | "nativeID" | "viewType" | "component", pattern: string): void;
+    /**
+     * Remove an exclude pattern
+     */
+    removeExcludePattern(type: "testID" | "nativeID" | "viewType" | "component", pattern: string): void;
+    /**
+     * Clear all filters
+     */
+    clearFilters(): void;
+    /**
+     * Get available prop values from tracked renders
+     */
+    getAvailableProps(): {
+        viewTypes: string[];
+        testIDs: string[];
+        nativeIDs: string[];
+        componentNames: string[];
+        accessibilityLabels: string[];
+    };
+    /**
+     * Get summary stats
+     */
+    getStats(): {
+        totalComponents: number;
+        totalRenders: number;
+    };
+    /**
+     * Subscribe to render updates
+     */
+    subscribe(listener: RenderTrackerListener): () => void;
+    /**
+     * Subscribe to state changes (tracking/paused)
+     */
+    subscribeToState(listener: StateListener): () => void;
+    /**
+     * Subscribe to settings changes
+     */
+    subscribeToSettings(listener: SettingsListener): () => void;
+    /**
+     * Subscribe to filter changes
+     */
+    subscribeToFilters(listener: FilterListener): () => void;
+    /**
+     * Check if a render should be visible based on current filters
+     * Used by the overlay to filter frozen highlights
+     */
+    shouldShowRender(render: TrackedRender): boolean;
+    /**
+     * Get current settings
+     */
+    getSettings(): RenderTrackerSettings;
+    /**
+     * Update settings
+     */
+    setSettings(newSettings: Partial<RenderTrackerSettings>): void;
+    /**
+     * Clear render history for all components
+     */
+    clearAllRenderHistory(): void;
+    /**
+     * Clear render history for a specific component
+     */
+    clearRenderHistory(id: string): void;
+    /**
+     * Get render history stats for debugging
+     */
+    getRenderHistoryStats(): {
+        totalEvents: number;
+        componentsWithHistory: number;
+        averageEventsPerComponent: number;
+    };
+    /**
+     * Get batch size (convenience method)
+     */
+    getBatchSize(): number;
+    /**
+     * Set batch size (convenience method)
+     */
+    setBatchSize(size: number): void;
+    private notifyListeners;
+    private notifyStateListeners;
+    private notifySettingsListeners;
+    private notifyFilterListeners;
+}
+export declare const RenderTracker: RenderTrackerSingleton;
+export default RenderTracker;
+//# sourceMappingURL=RenderTracker.d.ts.map