Fluxy DevTools

Fluxy DevTools provides a suite of tools for Stability Management, guarding against categories of crashes that standard Flutter apps often succumb to.

1. The Stability Kernel

Fluxy proactively scans your widget tree for violations. You control its aggression level using Fluxy.setStrictMode(bool).

Strict vs. Relaxed Mode

1. Relaxed Mode (Default): Designed for Production.

   • Behavior: When a crash-inducing error is detected, Fluxy auto-repairs it, logs a silent warning, and keeps the app running.
   • Goal: Ensure 99.99% uptime. Users should never see a "Grey Screen of Death".
   • Trade-off: May introduce minor performance hits (e.g., auto-applied shrinkWrap) to save the crash.

2. Strict Mode: Designed for Development.

   • Behavior: Intentionally throws a FluxyLayoutViolationException immediately upon detection.
   • Goal: Force you to fix the root cause instead of relying on Fluxy's safety net.

Recommendation: Always enable Strict Mode in debug builds to catch "lazy" layout practices that Fluxy is secretly fixing for you.

void main() async {
  await Fluxy.init();
  
  // Enable strict mode locally to catch bugs early
  if (kDebugMode) {
    Fluxy.setStrictMode(true); 
  }
  
  runApp(MyApp());
}

2. Crash Prevention Categories

Fluxy automatically wraps common primitives (like Fx.scaffold, Fx.col, Fx.scroll) in its internal guards (FluxyViewportGuard, FxSafeExpansion), making manual SafeArea or constraint checks often redundant.

Type A: Layout Crashes (The "Red Screen")

Fluxy translates cryptic RenderFlex errors into readable alerts.

Type B: Render & Paint Crashes

These occur deeper in the pipeline, often freezing the UI thread.

1. Dual Infinity:
   • Crash: A widget requests double.infinity for both width and height without a parent boundary.
   • Fix: Fluxy clamps the size to the window dimensions.
2. NaN Geometry:
   • Crash: Calculating a size of NaN or Infinity (e.g., dividing by zero in a custom painter).
   • Fix: RenderStabilityGuard detects invalid geometry and falls back to 0x0.
3. Painting Exceptions:
   • Crash: An error thrown during paint().
   • Fix: FluxyRenderGuard catches the exception and draws a red placeholder box instead of crashing the entire route.

Type C: Async & Lifecycle Crashes

1. "SetState() after dispose()":
   • Crash: An async API call returns after the user navigates away, trying to update a disposed widget.
   • Fix: FluxyAsyncGuard checks context.mounted before every reactive update and silently drops the frame if unmounted.

3. Visual Layout Inspector

Wrap your app root to enable the visual inspector overlay.

void main() {
  runApp(
    Fluxy.debug(
      child: MyApp(),
    ),
  );
}

• Toggle Inspector: Shake device or press the on-screen generic button.
• Highlight Overflows: Draws red boxes around widgets that are clipping or overflowing.
• Repaint Rainbow: visualized to debug excessive rebuilds.

4. Stability Metrics

Fluxy tracks every intercepted crash and auto-repair. You can view this summary to audit your app's health.

Interpreting the Report

• Prevented Crashes: Critical errors that would have stopped the app (e.g., Paint exceptions).
• Layout Repairs: "Lazy" code fixes (e.g., Infinite Scroll) that you should fix in Strict Mode.
• Viewport Saves: Number of times FluxyViewportGuard prevented content from being clipped or hidden.

Example: Log on Crash

Hook into your global error handler to print the stability report whenever an exception occurs.

void main() {
  Fluxy.onError((error, stack) {
    debugPrint("Fluxy Global Error: $error");
    
    // Check if the system was already unstable
    Fluxy.printStabilitySummary(); 
  });

  runApp(MyApp());
}

Sample Output:

[Fluxy Stability] Session Report:
- Prevented Crashes: 3
- Layout Repairs: 12
  - Infinite Scroll Fixed: 8
  - Safe Expansion Triggered: 4
- Viewport Saves: 5

By understanding these metrics, you can audit your codebase for "silent failures" that Fluxy is handling for you.