flutter_debug_badges 0.1.2

Debug overlay & section marker badges for Flutter apps. Integrates with Dev Pilot to show clickable route/page info and section markers in debug mode.

Flutter Debug Badges

Lightweight debug overlay & section marker badges for Flutter apps.
Prints structured markers ([DebugOverlay], [DebugSection]) to the terminal that can be parsed by a compatible frontend (like Dev Pilot) into clickable badges.

---

Features

• 📍 Debug Overlay — Shows the current route + file name in a top bar (debug mode only).
  • Auto-detects route from GoRouter; falls back to a custom route→file mapping.
  • Supports page hints for tabs/sub-pages that share the same route.
• 📄 Debug Section — Wraps any widget and prints a [DebugSection] marker each time it builds.
  • Clicking on the widget label also prints [DebugOverlaySection] so the frontend can update the overlay breadcrumb.
  • No dedup — always prints on every build, so frontend badges update on hot reload.
• 🧩 Dev Pilot Badges Integration — The process-manager client includes DebugOverlayBadges.tsx that parses these markers and renders clickable badges inside the process log panel.

---

Usage

1. Add dependency

dependencies:
  flutter_debug_badges: ^0.1.0

2. Import

import 'package:flutter_debug_badges/flutter_debug_badges.dart';

3. Wrap your app with DebugOverlay

MaterialApp.router(
  routerConfig: router,
  builder: (context, child) {
    return DebugOverlay(
      router: router,
      child: child!,
    );
  },
)

Custom route→file mapping

By default, routes that are not in the built-in mapping show as unknown_page.dart. Provide a custom map to override:

DebugOverlay(
  router: router,
  child: child!,
  routeFileMap: {
    '/dashboard': 'dashboard_page.dart',
    '/profile': 'profile_page.dart',
    '/settings': 'settings_page.dart',
  },
  defaultFile: 'app.dart',
  unknownFile: 'unknown_page.dart',
)

4. Wrap sections with DebugSection

DebugSection(
  fileName: 'dashboard_header.dart',
  child: HeaderWidget(),
)

Use fullPage: true when wrapping an entire page (child gets an Expanded):

DebugSection(
  fileName: 'login_page.dart',
  fullPage: true,
  child: LoginForm(),
)

5. Page hints for tabs/sub-pages

When multiple tabs share the same route (e.g. /dashboard for both dashboard and layanan tabs), call DebugOverlay.setPageHint() to disambiguate:

// In the tab's build or initState:
DebugOverlay.setPageHint('layanan_page.dart');

When returning to the main page, reset with null:

DebugOverlay.setPageHint(null); // falls back to route→file mapping

---

Markers Format

These markers are debugPrint'ed and can be parsed by a log viewer:

Marker	Format	Example
Overlay	[DebugOverlay] 📁 {file} | {route}	[DebugOverlay] 📁 dashboard_page.dart | /dashboard
Section	[DebugSection] 📄 {file}	[DebugSection] 📄 dashboard_top_header.dart
Section tap	[DebugOverlaySection] 📁 {file}	[DebugOverlaySection] 📁 dashboard_top_header.dart

---

Dev Pilot Integration

This package is designed to work with Dev Pilot, a process manager that captures Flutter debug output and renders badges from these markers.

The DebugOverlayBadges.tsx component:

• Parses markers from the latest process log
• Shows the overlay file as a 📍 badge (with route breadcrumb)
• Shows all unique 📄 section badges that appeared after the latest overlay
• Clicking a section badge copies the filename and updates the overlay breadcrumb

---

Notes

• Debug mode only — DebugOverlay and DebugSection are no-ops in release/profile builds.
• Lightweight — Only depends on go_router. Compressed size ~4 KB.
• GoRouter required — DebugOverlay uses GoRouter.routerDelegate to listen to route changes.