philiprehberger_state_inspector

Debug overlay showing state changes, rebuild counts, and transition history

Requirements

• Dart >= 3.6
• Flutter >= 3.29

Installation

Add to your pubspec.yaml:

dependencies:
  philiprehberger_state_inspector: ^0.4.0

Then run:

flutter pub get

Usage

import 'package:philiprehberger_state_inspector/state_inspector.dart';

final inspector = StateInspector.instance;

// Log state changes
inspector.logState('counter', '1', previous: '0');
inspector.logState('theme', 'dark');

// Track widget rebuilds
inspector.trackRebuild('CounterWidget');

Showing the Overlay

StateInspector extends ChangeNotifier, so wrap the overlay in a ListenableBuilder for automatic updates:

ListenableBuilder(
  listenable: StateInspector.instance,
  builder: (context, _) {
    if (!StateInspector.instance.isVisible) return const SizedBox.shrink();
    return InspectorOverlay(
      logger: StateInspector.instance.logger,
      tracker: StateInspector.instance.tracker,
      performance: StateInspector.instance.performance,
      onClose: () => StateInspector.instance.hide(),
    );
  },
)

Performance Tracking

// Record frame durations
inspector.trackFrame(const Duration(milliseconds: 16));

// Query metrics
final fps = inspector.performance.estimatedFps;
final avg = inspector.performance.averageFrameTimeMs;
final peak = inspector.performance.peakFrameTimeMs;
final frames = inspector.performance.frameCount;

Custom Markers

Record named timestamps and measure the elapsed time between them:

inspector.performance.recordMark('fetch:start');
await fetchData();
inspector.performance.recordMark('fetch:end');

final elapsed = inspector.performance.measureMark(
  'fetch:start',
  'fetch:end',
);
// Returns Duration.zero if either mark was never recorded.

Exporting Data

// Export state history as JSON
final jsonData = inspector.logger.exportJson();

// Export state history as CSV
final csvString = inspector.logger.exportCsv();

Draggable Overlay

Wrap the InspectorOverlay in a DraggableOverlay for repositionable panels:

DraggableOverlay(
  initialPosition: const Offset(16, 100),
  child: InspectorOverlay(
    logger: StateInspector.instance.logger,
    tracker: StateInspector.instance.tracker,
    performance: StateInspector.instance.performance,
    onClose: () => StateInspector.instance.hide(),
  ),
)

Querying State History

final allEntries = inspector.logger.all;
final recentEntries = inspector.logger.recent(5);
final counterEntries = inspector.logger.filterByLabel('counter');
final exported = inspector.logger.export();

Querying Rebuild Counts

final count = inspector.tracker.count('CounterWidget');
final topRebuilders = inspector.tracker.topRebuilders(5);
final totalRebuilds = inspector.tracker.total;

API

Method	Description
StateInspector.instance	Shared singleton instance
StateInspector.logState()	Record a state change with label and value
StateInspector.trackRebuild()	Record a widget rebuild
StateInspector.show()	Show the overlay
StateInspector.hide()	Hide the overlay
StateInspector.toggle()	Toggle overlay visibility
StateInspector.reset()	Clear all tracked data
StateInspector.trackFrame()	Record a frame duration
StateInspector.performance	Access performance metrics
StateLogger.add()	Add a state entry
StateLogger.all	All recorded entries
StateLogger.recent(n)	Most recent n entries
StateLogger.filterByLabel()	Filter entries by label
StateLogger.clear()	Remove all entries
StateLogger.count	Total number of entries
StateLogger.export()	Export as formatted string
StateLogger.exportJson()	Export as JSON array
StateLogger.exportCsv()	Export as CSV string
StateLogger.diffSince(window)	Entries recorded within the given Duration window
PerformanceMetrics.recordFrame()	Record a frame duration
PerformanceMetrics.recordMark(name)	Record a named timestamp marker
PerformanceMetrics.measureMark(start, end)	Duration between two marks (zero if either missing)
PerformanceMetrics.averageFrameTimeMs	Average frame time in ms
PerformanceMetrics.peakFrameTimeMs	Peak frame time in ms
PerformanceMetrics.estimatedFps	Estimated FPS
PerformanceMetrics.frameCount	Total frames tracked
PerformanceMetrics.reset()	Reset all metrics
PerformanceMetrics.toJson()	Export metrics as map
DraggableOverlay	Draggable wrapper for debug panels
RebuildTracker.increment()	Record a widget rebuild
RebuildTracker.count()	Get rebuild count for a widget
RebuildTracker.topRebuilders(n)	Top n most rebuilt widgets
RebuildTracker.reset()	Clear all counts
RebuildTracker.total	Total rebuilds across all widgets

Development

flutter pub get
flutter analyze --fatal-infos
flutter test

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT