docs(flutter): Add ANR and App Hangs guidance

docs/platforms/dart/guides/flutter/configuration/anr-app-hangs.mdx

@@ -0,0 +1,60 @@
+---
+title: ANR and App Hangs
+description: "Learn how Sentry detects and configures ANRs and App Hangs in Flutter apps."
+sidebar_order: 45
+---
+
+Sentry can detect when your Flutter app's main thread is blocked for too long, causing the app to become unresponsive. The Flutter SDK relies on the underlying native Sentry SDKs to detect these events.
+
+**This feature is available on Android, iOS, and macOS.**
+
+## What Gets Reported
+
+On Android, these are reported as Application Not Responding (ANR) events.
+On iOS and macOS, they're reported as App Hang events.
+Depending on where the app was blocked, events can include stack frames from Dart, Java/Kotlin, Swift/Objective-C, or C/C++ code.
+
+## Configure Detection
+
+ANR and App Hang detection are enabled by default. You can disable them or change their timeout thresholds in `SentryFlutter.init`:
+
+```dart
+await SentryFlutter.init(
+  (options) {
+    // Android only: ANR
+    options.anrEnabled = true; // default: true
+    options.anrTimeoutInterval = const Duration(seconds: 5); // default: 5s
+
+    // iOS/macOS only: App Hang
+    options.enableAppHangTracking = true; // default: true
+    options.appHangTimeoutInterval = const Duration(seconds: 2); // default: 2s
+  },
+);
+```
+
+For more configuration details, see the <Link to="/platforms/android/configuration/app-not-respond/">Android ANR documentation</Link> and the <Link to="/platforms/apple/configuration/app-hangs/">Apple App Hangs documentation</Link>.
+
+## Pause App Hang Tracking
+
+On iOS and macOS, you can pause App Hang tracking at runtime. Use this when you can't avoid a known blocking operation, such as a synchronous database migration during startup, and don't want Sentry to report it as an app hang.
+
+```dart
+SentryFlutter.pauseAppHangTracking();
+
+// Run code that you don't want Sentry to report as an app hang.
+
+SentryFlutter.resumeAppHangTracking();
+```
+
+## Readable Stack Traces
+
+Since ANR and App Hang events can include frames from Dart, Java/Kotlin, Swift/Objective-C, and C/C++ code, some frames require platform-specific debug files to appear readable in Sentry.
+
+See the <PlatformLink to="/debug-symbols/dart-plugin/">Sentry Dart Plugin documentation</PlatformLink> for the debug files required on Android, iOS, and macOS.
+
+## Platform Details
+
+For more details about how each native SDK detects these events, see:
+
+- [Android ANR documentation](/platforms/android/configuration/app-not-respond/)
+- [Apple App Hangs documentation](/platforms/apple/configuration/app-hangs/)

docs/platforms/dart/guides/flutter/configuration/options.mdx

@@ -34,7 +34,7 @@ Enabling `debug` mode makes the SDK generate as much diagnostic data as possible
 
 - `debug`: The most verbose mode
 - `info`: Informational messages
-- `warning`:  **default** Warning that something might not be right
+- `warning`: **default** Warning that something might not be right
 - `error`: Only SDK internal errors are printed
 - `fatal`: Only critical errors are printed
 
@@ -361,7 +361,7 @@ Set this boolean to `false` to disable reporting all the package dependencies.
 
 <SdkOption name="anrEnabled" type="bool" defaultValue="true">
 
-Set this boolean to `true` to enable ANR (Application Not Responding) detection on Android.
+Set this boolean to `true` to enable ANR (Application Not Responding) detection on Android. Learn more in <PlatformLink to="/configuration/anr-app-hangs/">ANR and App Hangs</PlatformLink>.
 
 </SdkOption>
 

docs/platforms/dart/guides/flutter/features/index.mdx

@@ -15,7 +15,7 @@ Sentry's Flutter SDK enables automatic reporting of errors and exceptions, and i
 - Automatic native crash error tracking (using both <Link to="/platforms/android">Android</Link> and <Link to="/platforms/apple/guides/ios">iOS</Link>), including:
   - Java, Kotlin, C, and C++ code for Android.
   - ObjC, Swift, and C for iOS.
-- Automatic detection of <Link to="/platforms/android/configuration/app-not-respond">Application Not Responding (ANR)</Link> on Android and <Link to="/platforms/apple/guides/ios/configuration/app-hangs/">App Hangs</Link> on iOS.
+- Automatic detection of <PlatformLink to="/configuration/anr-app-hangs/">Application Not Responding (ANR) and App Hangs</PlatformLink>.
 - Offline storage of events.
 - Events <PlatformLink to="/enriching-events/context">enriched</PlatformLink> with device data.
 - Breadcrumbs automatically captured:
@@ -25,23 +25,46 @@ Sentry's Flutter SDK enables automatic reporting of errors and exceptions, and i
 - Integrations for sqflite, routing and more. For a complete list, see <PlatformLink to="/integrations">integrations</PlatformLink>.
 - <Link to="/product/releases/health">Release Health</Link> tracks crash free
   users and sessions.
-- <PlatformLink to="/enriching-events/attachments">Attachments</PlatformLink> that
-  can enrich your event by storing additional files, such as config or log
+- <PlatformLink to="/enriching-events/attachments">Attachments</PlatformLink>
+  that can enrich your event by storing additional files, such as config or log
   files.
-- <PlatformLink to="/tracing">Tracing</PlatformLink> that can track:
-    - <PlatformLink to="/integrations/app-start-instrumentation">App start time</PlatformLink>
-    - <PlatformLink to="/integrations/routing-instrumentation/#time-to-initial-display">Time to Initial Display and Time to Full Display</PlatformLink>
-    - <PlatformLink to="/integrations/slow-and-frozen-frames-instrumentation">Slow and Frozen Frames</PlatformLink>
-    - <PlatformLink to="/integrations/user-interaction-instrumentation">User Interaction</PlatformLink> which include clicks, long clicks, taps and so on.
-    - For a complete list see <PlatformLink to="/tracing/instrumentation/automatic-instrumentation">automatic instrumentations</PlatformLink>.
+- <PlatformLink to="/tracing">Tracing</PlatformLink> that can track
+  <PlatformLink to="/integrations/app-start-instrumentation">
+    app start time
+  </PlatformLink>
+  ,
+  <PlatformLink to="/integrations/routing-instrumentation/#time-to-initial-display">
+    Time to Initial Display and Time to Full Display
+  </PlatformLink>
+  ,
+  <PlatformLink to="/integrations/slow-and-frozen-frames-instrumentation">
+    Slow and Frozen Frames
+  </PlatformLink>
+  , and
+  <PlatformLink to="/integrations/user-interaction-instrumentation">
+    User Interaction
+  </PlatformLink>
+  . For a complete list, see
+  <PlatformLink to="/tracing/instrumentation/automatic-instrumentation">
+    automatic instrumentations
+  </PlatformLink>
+  .
 - <PlatformLink to="/user-feedback">User Feedback</PlatformLink>, providing the
   ability to collect user feedback when an unexpected event occurs.
-- <PlatformLink to="/enriching-events/screenshots">Screenshot</PlatformLink> and <PlatformLink to="/enriching-events/viewhierarchy">View Hierarchy</PlatformLink> attachments for errors.
+- <PlatformLink to="/enriching-events/screenshots">Screenshot</PlatformLink> and
+  <PlatformLink to="/enriching-events/viewhierarchy">
+    View Hierarchy
+  </PlatformLink>
+  attachments for errors.
 - <PlatformLink to="/profiling">Profiling</PlatformLink> collects detailed
-  information about your code at the function level.
-    - Profiling is currently supported on **iOS** and **macOS**.
-    - It captures profiles across multiple language layers, including native languages (such as Swift and Objective-C) as well as Dart.
-- <PlatformLink to="/data-management/debug-files/source-context">Source Context</PlatformLink> shows snippets of code around the location of stack frames.
+  information about your code at the function level. Profiling is currently
+  supported on **iOS** and **macOS**, and captures profiles across multiple
+  language layers, including native languages (such as Swift and Objective-C) as
+  well as Dart.
+- <PlatformLink to="/data-management/debug-files/source-context">
+    Source Context
+  </PlatformLink>
+  shows snippets of code around the location of stack frames.
 - <PlatformLink to="/upload-debug">Sentry Dart Plugin</PlatformLink> makes
   uploading debug symbols easy and automatic.
 - <PlatformLink to="/metrics">Metrics</PlatformLink> allow you to send counters,