flutter_blackbox 0.6.1

All-in-one in-app debug overlay for Flutter. Network inspector, API mocking, live logs, FPS monitor, rebuild tracker, storage inspector, crash reports, and QA tools.

Changelog

0.6.1 - 2026-05-27

Fixed

• pub.dev Layout: Switched README screenshot sizes to percentage-based widths so they properly scale and align side-by-side on pub.dev's narrower container without wrapping.

0.6.0 - 2026-05-22

Added

• Mini HUD Mode: The floating draggable trigger button now morphs into a Mini HUD when dragged to the bottom edge. It displays live FPS, the latest HTTP status code, and crash count, without needing to open the full panel.
• Copy as cURL: Added a button to the Network detail view to instantly copy any request as a valid cURL command.
• Export HAR: Added a button to the Network toolbar to export all network requests as an industry-standard HAR (HTTP Archive) 1.2 JSON string, importable into Postman, Insomnia, or Chrome DevTools.
• Selectable Text: Replaced static text with SelectableText in the Log panel and Network JSON viewer for easy highlighting and copying of specific snippets.
• Staggered Animations: Wrapped NetworkCard and LogTile in a new StaggeredListItem wrapper, creating a premium cascading slide-up and fade animation when lists are rendered.
• Isolate JSON Parsing: Large JSON responses (>50KB) are now parsed in a background isolate (compute) via JsonIsolate.decode() to prevent UI thread jank when opening the Network panel.
• Swipe-to-Dismiss: Network and Log entries can now be individually deleted by swiping left-to-right, with haptic feedback and a red delete indicator.
• Scroll-to-Top FAB: Both Network and Log panels now show a floating accent-colored arrow button after scrolling 300px, providing one-tap smooth scroll back to the top.
• Pull-to-Refresh: All scrollable panels (Network, Log, Rebuild) now support pull-to-refresh with haptic feedback. Pulling on the Rebuild panel resets all rebuild counts.
• Left Accent Borders: Network rows display a 3px color-coded left border (green for 2xx, amber for 4xx, red for 5xx, grey for pending). Log rows similarly show a left accent matching their log level color for instant visual scanning.
• Haptic Feedback on Tab Switch: Switching between overlay tabs now triggers a subtle selectionClick haptic for a tactile, premium feel.
• Glassmorphic Device Panel: Device panel rebuilt with frosted-glass section cards (Platform, Screen, App), each with a BackdropFilter blur, gradient background, accent-colored section headers with icons, and monospace values.

Changed

• Store Capacities: Increased default store capacities for longer QA sessions without losing data: NetworkStore (50 -> 500), LogStore (200 -> 1000), and CrashStore (20 -> 100).
• Default Panel Height: Overlay default open size increased from 85% to 95% screen height for a more immersive debug experience.
• Uniform Tab Widths: All tab buttons now use a fixed 56px width with ellipsized labels, eliminating uneven tab sizing across different screen widths.
• Glassmorphic Polish: Upgraded the overlay header and panel cards with higher BackdropFilter sigma (28), gradient top-edge shines, refined border styles, and soft shadows for a premium frosted-glass aesthetic.
• Consistent Monospace Fonts: Timestamps in Log panel and values in Device panel now use monospace font for improved readability and alignment.

Performance

• Implicit Animations: Replaced AnimationController + SingleTickerProviderStateMixin in StaggeredListItem with lightweight AnimatedOpacity + AnimatedSlide. For a list of 200 items, this eliminates 200 animation controller allocations.
• EmptyState Optimization: Converted EmptyState from StatefulWidget to StatelessWidget with an isolated _FloatingEmoji sub-widget. The floating emoji animation no longer forces the entire empty state to be stateful.
• ListView cacheExtent: Added cacheExtent: 500 to Network and Log panel ListView.builder instances, pre-building ~500px of off-screen items for smoother scrolling with zero visible pop-in.
• TickerMode on Inactive Tabs: _LazyIndexedStack wraps inactive panels with TickerMode(enabled: false), disabling all animation tickers for panels not currently visible — zero background animation overhead.

Fixed

• Web/WASM Compatibility: Eliminated the final dart:io dependency (HttpClient) in NetworkReplayer by using conditional imports (network_replayer_stub.dart). The package is now 100% compliant with Flutter Web/WASM compilation.
• Theme Bleed-Through: Wrapped the entire BlackBoxOverlay in a standalone Theme(data: ThemeData.dark()) to prevent the host application's themes (like light mode or custom fonts) from bleeding into the debug overlay on Web environments.
• RepaintBoundary Isolation: Wrapped _DraggableFloatingButton and _ResizablePanel in RepaintBoundary to prevent the host app from repainting when BlackBox animations (like the floating button breathing effect) occur.
• Double-Close Race Condition: Fixed a bug where rapidly tapping the close button would trigger multiple haptic feedbacks and duplicate animation callbacks. Added an early return guard and immediate visibility flag to prevent re-entry.
• Tab Switch Flicker: Eliminated first-paint flicker when switching tabs by using a warm-up frame strategy — new panels are built invisibly for one frame before fading in via AnimatedOpacity.
• Keyboard Overlay Shift: Fixed the overlay shifting upward when the keyboard opens by using a stable GlobalKey<NavigatorState> to prevent unnecessary Navigator rebuilds triggered by MediaQuery changes.

0.5.3 - 2026-05-21

Fixed

• README CI Badge Caching: Appended cache-busting arguments to the GitHub Actions status badge in README.md to force pub.dev and browsers to fetch the newly passing (green) CI status.

0.5.2 - 2026-05-21

Fixed

• CI & Test Suite Stability: Fixed an issue where the new infinite AnimatedSize and floating emoji animations were causing flutter_test timeouts (pumpAndSettle). Animations now correctly pause during widget testing environments.
• Strict Linting: Fixed minor strict analyzer rules enforced by flutter_lints ^6.0.0 (dangling doc comments, unused imports, print statements).
• GitHub Actions: Fixed CI workflow to correctly run dart format and pass all strict static analysis checks.

0.5.1 - 2026-05-21

Added

• Gorgeous UI Animations: Added buttery-smooth AnimatedSize transitions for expanding Network request JSON bodies, Socket event details, and Navigation route cards.
• Animated Empty States: Upgraded all empty state screens (Network, Logs, Sockets, Navigation, Rebuilds, Storage) with subtle, floating emoji animations to dramatically improve the default UX.
• QA Panel Overhaul: Ripped out the default FilterChip severity selectors and replaced them with fully custom AnimatedContainer buttons featuring smooth cross-fading text and vibrant, highly-visible background colors.
• Floating Button Breathing Animation: Added a subtle, continuous scaling pulse ("breathing") animation to the draggable floating trigger button so it feels alive.

Changed

• Resizable Bottom Sheet: The overlay now defaults to 85% screen height (resembling a native bottom sheet) rather than 100%. The new transparent top drag-handle lets users instantly snap the panel between 50% and 85% height.

Fixed

• Maximum Pub Points: Upgraded flutter_lints to v6.0.0, eliminated all minor lint warnings (like unnecessary_library_name), and verified a flawless 160/160 pub.dev score via the official pana engine.
• Fixed relative image paths in README.md not resolving on pub.dev due to HTML <img> tag URL rewriting limitations. Replaced with absolute raw GitHub URLs.

0.5.0 - 2026-05-14

Added

• BlackBoxObserver API (Crashlytics/Sentry Integration): Professional teams can now forward BlackBox telemetry to external tools automatically without breaking the zero-dependency rule.
  • Listen to onCrash, onNetworkError, onNetworkResponse, and onLog.
  • Added CrashEntry.toFormattedString() to instantly generate beautiful, readable text payloads for Slack webhooks or custom logging APIs.
• Auto-Generated Crashlytics Adapter: If the flutter_blackbox:init CLI tool detects firebase_crashlytics in your pubspec.yaml, it automatically generates a CrashlyticsObserver implementation specifically tagged for easy filtering in the Firebase dashboard.
• Enterprise Trust Signals: Added a comprehensive CONTRIBUTING.md and structured GitHub Issue templates for bug reports and feature requests.
• CI/CD Pipeline: Added GitHub Actions workflow to strictly enforce dart format, dart analyze, and pana scoring.
• SEO & Discoverability: Updated pubspec.yaml description with targeted keywords and linked GitHub Sponsors in the funding key.
• Storage Panel — Destructive Action Guard: Added a confirmation dialog before "Clear All" in the Storage Inspector to prevent accidental data loss.

Fixed

• Crash — Empty Connectivity Result: Fixed StateError: No element crash in platform_info_impl.dart when connectivity_plus returns an empty result list. Added isNotEmpty guard before accessing .first.
• Memory Leak — Duplicate FPS Callbacks: FpsMonitor.start() called after stop() would register a second permanent frame callback via addPersistentFrameCallback (which cannot be removed). Added a _callbackRegistered flag to ensure exactly one callback exists.
• Memory Leak — Setup Teardown: BlackBox.setup() teardown was missing fpsMonitor.stop(), leaving orphaned frame callbacks when re-initializing.
• Platform Error Double-Reporting: PlatformDispatcher.onError override was hardcoded to return false, ignoring the original handler's return value. This caused errors to double-report to the default handler even when the app's original handler already handled them. Now correctly forwards the return value.
• Stale JSON in Network Panel: _CollapsibleJsonSection cached parsed JSON only in initState via late final. When the widget was rebuilt with new data (e.g., a response arriving while expanded), it would display stale content. Added didUpdateWidget to re-parse on data changes.
• setState-after-dispose in Storage Panel: Added mounted guards to _deleteKey(), _clearAll(), _editValue(), and _addNewKey() after their async adapter calls. Without these, switching tabs or closing the overlay during an in-flight storage operation would trigger a framework warning.

Changed

• Shortened pubspec.yaml description to 165 characters (was 234) to comply with pub.dev's 180-character limit and restore 10/10 convention points.
• All code formatted with dart format — 0 formatting issues.

---

0.4.0 - 2026-05-05

Performance

• Lazy Panel Loading: Replaced eager TabBarView (which instantiated all 9 panels at startup) with a custom _LazyIndexedStack that defers panel creation until first navigation. Reduces initial memory footprint by ~60%.
• Search Debouncing: Added 300ms input debounce to SearchPanel to prevent UI thread thrashing during intensive cross-panel searches.
• O(1) Network Lookups: Refactored NetworkStore from O(N) linear scans to O(1) Map-based indexing for response matching.
• Single-Pass Filter Counts: Optimized NetworkPanel status filter chip counts from 6× O(N) chained .where() calls to a single O(N) pass.
• FPS Syscall Elimination: Replaced DateTime.now() inside the 60fps frame callback with the engine-provided timestamp parameter.
• FPS Graph Repaint Fix: Fixed _FpsGraphPainter.shouldRepaint which was using reference inequality (!=) instead of listEquals, causing unnecessary repaints on every frame.
• Log Store Lazy Iteration: Changed LogStore.filter() return type from List to Iterable, avoiding unnecessary list allocations during filtering.
• Log Panel itemExtent: Added fixed itemExtent to ListView.builder in LogPanel for O(1) scroll offset calculations.
• Crash Store Throttling: Added notification throttling to CrashStore to batch rapid crash report emissions.
• String Allocation Reduction: Extracted .toLowerCase() query transformations outside of .where() filter loops in StoragePanel and SocketPanel to prevent redundant allocations per list item.
• Jank Count Caching: Cached the O(N) jankyFrameCount getter result in a local variable inside the _JankSummary build method, eliminating 3× redundant array traversals per frame.

Fixed

• Memory Leak — Keyboard Handler: Fixed BlackBoxOverlay not removing its keyboard event handler on dispose(), causing a permanent reference leak.
• Memory Leak — Screenshot Bytes: Added cleanup of heavy screenshot Uint8List data in QaPanel.dispose().
• Idempotent Setup: BlackBox.setup() is now idempotent — calling it multiple times no longer causes double-registration of error handlers or adapters.
• Safe Dispose: BlackBox.dispose() now fully resets global state, nullifies stores, and cancels all stream subscriptions.
• Platform Info Crash: Fixed StateError in platform_info_impl.dart when accessing views on platforms with no implicit view.
• MockResponse Recursion: Fixed infinite recursion in MockResponse.copyWith caused by incorrect isEnabled parameter forwarding.
• QA Panel Magic Numbers: Replaced magic index comparisons with proper LogLevel enum values in QaPanel.
• StoragePanel Form Field: Corrected deprecated value parameter to initialValue in DropdownButtonFormField.

Changed

• All code formatted with dart format to comply with Dart conventions and maintain 160/160 pub.dev score.

0.3.6 - 2026-05-01

Added

• Performance Optimizations: Resolved overlay toggle lag by replacing full Navigator rebuilds with Offstage and IgnorePointer. Toggling the overlay is now completely instantaneous.
• Improved Responsiveness: Replaced GestureDetector with Listener on the floating trigger button to bypass gesture disambiguation delays.
• Integrated Global Search: Relocated the Global Search button from a dedicated tab into the panel header for faster access and reduced tab clutter.

Fixed

• Platform Support (WASM): Resolved an issue where pana unfairly deducted 10 points for "WASM incompatibility". package_info_plus, device_info_plus, and connectivity_plus dependencies are now stubbed on the web using dart.library.js_interop conditional imports, completely shielding the package from dart:io WASM incompatibility errors. The package now scores a perfect 160/160 on pub.dev.
• Formatted codebase to comply with Dart conventions.

0.3.5 - 2026-05-01

Fixed

• Missing File Compile Error: Added deprecation shims for lib/adapters/dio.dart, http.dart, shared_prefs.dart, and socket_io.dart. This prevents fatal compilation errors for users upgrading from v0.2.x who still have the old import paths in their projects.
• Migration Guide: Corrected the CHANGELOG migration guide which incorrectly told users to import the deleted adapter files.

0.3.4 - 2026-04-29

Fixed

• Pinned connectivity_plus to >=7.0.0 <7.1.0 to resolve an iOS compile error (Value of type 'NWPath' has no member 'isUltraConstrained') introduced in 7.1.x. That API is only available on iOS 16+ but was used without an #available check, breaking apps with lower minimum deployment targets.

0.3.3 - 2026-04-29

Fixed

• CLI --generate duplicate httpAdapters key — when both dio and http were present in pubspec.yaml, the generator emitted two separate httpAdapters: named arguments inside BlackBox.setup(), which is a Dart compile error. Both adapters are now merged into a single httpAdapters: [DioBlackBoxAdapter(dio), HttpBlackBoxAdapter(httpClient)] list.
• CLI --generate imports placed after class bodies — each adapter template previously embedded its own import statements at the top of the template string. When two or more adapters were generated into the same file, the second template's imports appeared after the first template's class declarations — invalid Dart. The generator now collects all imports first (deduplicated), writes them at the top of the file, then writes all class bodies. dart:convert is no longer duplicated when both Dio and http adapters are present.
• HttpBlackBoxAdapter._sanitiseHeaders return type — the return type was incorrectly declared as Map<String, dynamic> instead of Map<String, String>, inconsistent with the Dio adapter and the NetworkRequest.headers field. Fixed to Map<String, String>.
• CLI printed hint also had duplicate httpAdapters — the non---generate setup hint printed to the terminal suffered the same duplication. The hint now groups all HTTP adapters into one httpAdapters: line.

---

0.3.2 - 2026-04-28

Fixed

• Upgraded connectivity_plus to ^7.1.0 (v7.1.x migrated web implementation to package:web instead of dart:html, restoring WASM compatibility on pub.dev).
• device_info_plus and package_info_plus upgraded to latest patch via dart pub upgrade (12.4.0 and 9.0.1 respectively).

---

0.3.1 - 2026-04-28

Fixed

• Widened dependency constraints to support latest major versions and restore full pub.dev score:
  • package_info_plus: >=9.0.0 <11.0.0 (was ^9.0.0, now supports v10.x)
  • device_info_plus: >=12.3.0 <14.0.0 (was ^12.3.0, now supports v13.x)
  • connectivity_plus: >=7.0.0 <8.0.0 (was ^7.0.0, explicit upper bound)
  • All APIs used (DeviceInfoPlugin, PackageInfo.fromPlatform, Connectivity.checkConnectivity) are stable and unchanged between these major versions.

---

0.3.0 - 2026-04-28

Added

• CLI Init Tool — dart run flutter_blackbox:init auto-detects your project's dependencies (Dio, http, Socket.IO, SharedPreferences) and prints the exact setup code you need.
  • --generate flag generates a lib/blackbox_adapters.dart file with only the adapters your project uses — zero unnecessary packages installed.
  • --help for full usage instructions.
• CLI-generated adapter architecture — concrete adapter implementations (DioBlackBoxAdapter, HttpBlackBoxAdapter, SocketIOBlackBoxAdapter, SharedPrefsStorageAdapter) are no longer bundled inside lib/. They are generated into the user's project by the CLI. This means:
  • flutter_blackbox has zero optional dependencies — 63 KB total package size.
  • Dio users don't get http, socket_io_client, or shared_preferences installed.
  • The generated lib/blackbox_adapters.dart is fully editable and customizable.
  • Same zero-setup pattern as build_runner, freezed, and injectable.
• Copy as cURL — one-tap button in Network panel copies any request as a valid curl command (with headers, body, method).
• Status Code Filtering — filter chips to show only 2xx, 4xx, 5xx, Pending, or Failed requests.
• Method Filtering — filter by HTTP method (GET, POST, PUT, DELETE, PATCH).
• Response Size Display — shows response body size (B/KB/MB) in each network tile and detail view.
• Request Timing Visualization — color-coded timing bars (green < 300ms, yellow < 1000ms, red > 1000ms) with speed indicator.
• Pretty JSON Viewer — collapsible, syntax-highlighted JSON tree with color-coded types. Auto-expands first level.
• Search Across All Panels — new "Search" tab that queries Network, Logs, Crashes, and Socket events simultaneously.
• Full Dartdoc Coverage — all public APIs, stores, and models now have comprehensive documentation for better IDE support and higher pub.dev scoring.
• Web Compatibility — removed dart:io dependencies from UI panels to ensure the package runs smoothly on Flutter Web.

Changed

• Full "devkit" → "BlackBox" rebrand — all file names, imports, internal references, and the overlay badge now use the BlackBox name consistently.
• Main barrel (flutter_blackbox.dart) exports only abstract interfaces (BlackBoxHttpAdapter, BlackBoxSocketAdapter, BlackBoxStorageAdapter). Concrete adapter implementations are generated into the user's project by the CLI.
• Moved dio, http, shared_preferences, socket_io_client from dependencies to dev_dependencies — users only install what they actually use.
• Overlay badge now shows "BlackBox" instead of "devkit".
• Internal Dio extras keys renamed from devkit_request_id/devkit_start_ms to blackbox_request_id/blackbox_start_ms.
• NetworkResponse model now includes optional responseSizeBytes field and formattedSize getter.
• Dio and HTTP adapters now capture response size automatically.
• Network panel detail view reorganized with timing summary card, collapsible JSON sections, and action buttons (cURL, Copy URL, Copy All).

Fixed

• Fixed duplicate property definitions in BlackBox singleton class.
• Fixed flaky broadcast stream tests in NetworkStore by accounting for event throttling.
• Added missing exports for JourneyEvent, FpsMonitor, and BlackBoxDeviceInfo to the main barrel file.

Performance

• NetworkPanel: Replaced two independent StreamBuilders on the same stream with a single StreamSubscription. Previously every network event triggered two separate rebuild cycles; now it triggers one.
• _NetworkTile: Cached the Uri.parse() result as late final _endpoint in initState/didUpdateWidget. URI parsing no longer runs on every build() call.
• _CollapsibleJsonSection: Replaced the _parsed computed getter with a late final field set in initState. jsonDecode now runs once per section lifecycle instead of on every rebuild.
• RebuildPanel: Converted to StatefulWidget + StreamSubscription. Removed the Stream.value(...) anti-pattern and the (context as Element).markNeedsBuild() framework hack.

Migration

• Concrete adapter classes (DioBlackBoxAdapter, HttpBlackBoxAdapter, etc.) are no longer shipped inside the package. They are now generated directly into your project by the CLI:

  # 1. Generate adapters (detects your pubspec.yaml dependencies automatically)
  dart run flutter_blackbox:init --generate
  

  // 2. Replace old adapter imports with the generated file
  // Before (v0.2.x)
  import 'package:flutter_blackbox/adapters/dio.dart';
  
  // After (v0.3.0+)
  import 'blackbox_adapters.dart';  // generated by CLI
  

0.2.2 - 2026-04-06

Fixed

• Added CHANGELOG updates and minor version bumps for successful pub.dev publication.

0.2.1 - 2026-04-06

Added

• ignoredRebuildWidgets config in BlackBox.setup() to allow overriding and muting noisy custom 3rd-party widgets in the Rebuild tab.
• Smart Noise Filters hardcoded over 100+ native Flutter framework base widgets (Text, AutomaticKeepAlive, Container, etc) and 60fps animators (LinearProgressIndicator) from tracking to prevent noise.

Fixed

• Corrected regex string parsing for Flutter framework's raw rebuild log output (Building/Rebuilding) so Rebuild Tracking accurately measures widget rebuilds rather than staying at zero.
• Rebuild Tracker console spam fixed. Intercepted framework logs are now securely routed to the UI tab while completely muted from terminal output for cleaner logging.
• Fixed infinite rendering loops where BlackBoxOverlay and RebuildTrackerWidget recursively logged themselves in the Rebuild store.

0.2.0 - 2026-03-24

Added

• Storage Inspector — inspect, search, edit, delete key-value pairs from any storage backend.
  • Built-in SharedPrefsStorageAdapter.
  • Adapter pattern (BlackBoxStorageAdapter) supports GetStorage, Hive, FlutterSecureStorage, etc.
• Privacy & Sensitive Data Redaction — keys matching common patterns (password, token, secret, jwt, etc.) auto-redacted.
  • Global toggle: redactSensitiveData in BlackBox.setup() (default: true).
  • 25+ built-in sensitive patterns, customizable per adapter.
  • Sensitive values show as •••••••• — can't be copied or edited.
• Widget Rebuild Tracker — track widget rebuild counts for performance bottlenecks.
  • Auto mode: debugPrintRebuildDirtyWidgets hook — zero code changes.
  • Manual mode: RebuildTracker widget wrapper (zero-cost in release builds via kDebugMode).
• Socket.IO Adapter — auto-capture all incoming socket events via socket.onAny().
  • SocketIOBlackBoxAdapter(socket) — no changes to socket code.
• HttpBlackBoxAdapter — observe-only adapter that takes your existing http.Client.

Changed

• Observe-only philosophy — all adapters now hook into libraries' built-in extension points without replacing trusted code.
• BlackBoxHttpClient is now @Deprecated — replaced by HttpBlackBoxAdapter(client).

Removed

• Feature Flags panel and LocalFlagAdapter — replaced by Storage Inspector and Rebuild Tracker.

0.1.4 - 2026-03-19

Fixed

• Bumped dio lower bounds to ^5.4.0 in pubspec.yaml to ensure compatibility with DioException and restore pub.dev points.

0.1.3 - 2026-03-19

Changed

• Renamed all public classes from DevKit to BlackBox to fully align with the new package name.

0.1.1 - 2026-03-19

Changed

• Updated README and internal configuration to correctly reflect the flutter_blackbox package name.

0.1.0 - 2025-03-19

Added

• Single-package release — Dio and http adapters bundled in core
• DevKitOverlay — tabbed debug panel above Navigator
• Network panel — request/response log with headers and body
• Mock engine — intercept any HTTP request with fake response
• Log panel — captures debugPrint() automatically
• Performance panel — live FPS graph and jank detection
• Feature flags panel — runtime toggle without restart
• Device panel — platform, screen, OS info
• QA Report — one-tap screenshot + logs + network bundle
• DioDevKitAdapter — Dio interceptor (included in core)
• DevKitHttpClient — http.Client drop-in (included in core)
• PrintLogAdapter — auto-captures debugPrint
• LocalFlagAdapter — in-memory feature flags