BugLens 🔍🐛

Flutter In-App QA & Developer Debugging Toolkit

BugLens is a unified in-app debugging, inspection, and QA issue-reporting SDK for Flutter applications running across all platforms (Android, iOS, Web, macOS, Windows, Linux).

It provides zero-boilerplate drop-in interceptors for Networking (Dio & HTTP), State Management (Bloc & Riverpod), Route Navigation, and Console Prints.

---

🌟 Key Features

• 🌐 Alice-Like Network Interceptor: Plug BugLens.dioInterceptor directly into Dio or HTTP clients to automatically record all requests, responses, headers, query params, payloads, latency, status badges, and generate ready-to-run cURL commands.
• 🧱 Drop-in State Interceptors: Attach BugLens.blocObserver or BugLens.riverpodObserver to automatically track state transitions and mutations without writing tracking code inside your business logic.
• 🖨️ Console Print Interceptor: Wrap your app in BugLens.runZonedApp() to automatically intercept standard print() statements into structured logs.
• 📐 Live UI & Widget Inspector: Tap any widget on screen at runtime to view its dimensions, global coordinates (x, y), route, parent & children hierarchy, and tap "Report This Widget" to pre-attach its metrics directly to a bug report.
• 📝 Structured Logger: High-capacity in-memory circular buffer with levels (VERBOSE, DEBUG, INFO, WARN, ERROR, FATAL), metadata inspection, and instant query searching.
• ❌ Automatic & Isolated Error Monitor: Catches unhandled FlutterError and PlatformDispatcher exceptions without crashing the host app.
• 🎨 Screenshot Annotation Studio: Draw freehand lines, arrows, rectangles, circles, text labels, markers, and blackout blur boxes over captured screens.
• 🛡️ Privacy & Redaction by Default: Automatically masks sensitive headers (Authorization, Cookie, X-Api-Key) and sensitive payload fields (password, token, secret, cvv, credit_card).

---

🚀 Getting Started

Add bug_lens to your pubspec.yaml:

dependencies:
  bug_lens: ^1.1.0

1. Initialize BugLens & Run App

import 'package:bug_lens/bug_lens.dart';
import 'package:flutter/material.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  BugLens.init(
    environment: BugLensEnvironment.dev,
    config: const BugLensConfig(
      enabled: true,
      maxLogs: 500,
      maxNetworkRequests: 200,
      maxErrors: 100,
    ),
  );

  // Automatically captures all `print()` outputs as BugLens logs
  BugLens.runZonedApp(() {
    runApp(const MyApp());
  });
}

2. Wrap with BugLensOverlay

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My Flutter App',
      // Attach the navigator observer for automatic route tracking
      navigatorObservers: [BugLens.navigatorObserver],
      home: const BugLensOverlay(
        child: HomeScreen(),
      ),
    );
  }
}

---

🔌 Plug-and-Play Interceptors

1. Dio Network Interceptor (Zero Manual Logging)

import 'package:dio/dio.dart';
import 'package:bug_lens/bug_lens.dart';

final dio = Dio();

// Simply add the interceptor — all HTTP calls, responses, and errors are recorded automatically!
dio.interceptors.add(BugLens.dioInterceptor);

2. Bloc / Cubit State Observer

import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:bug_lens/bug_lens.dart';

void main() {
  // Automatically logs all Bloc events, transitions, changes, and errors!
  Bloc.observer = BugLens.blocObserver;
  runApp(const MyApp());
}

3. Riverpod State Observer

import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:bug_lens/bug_lens.dart';

void main() {
  runApp(
    ProviderScope(
      observers: [BugLens.riverpodObserver], // Automatically tracks Riverpod provider updates
      child: const MyApp(),
    ),
  );
}

---

💡 How to Open BugLens

1. Floating Trigger Button: Tap the floating bug icon on screen (draggable, snaps to screen bounds, displays an error badge when issues occur).
2. Keyboard Shortcut: Press Ctrl+Shift+B (Windows/Linux) or Cmd+Shift+B (macOS) on Web & Desktop.
3. Programmatic Triggers:

   BugLens.open();    // Open console HUD
   BugLens.report();  // Open QA Bug Reporter directly
   BugLens.inspect(); // Activate Live Widget Inspector
   BugLens.close();   // Close console
   

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.