docs(flutter): Add v10 migration guide and interactive checklist

docs/platforms/dart/guides/flutter/migration.mdx → docs/platforms/dart/guides/flutter/migration/index.mdx

@@ -1,15 +1,20 @@
 ---
 title: Migration Guide
 sidebar_order: 8000
+description: "Learn how to migrate your Flutter application between major versions of the Sentry SDK."
 ---
 
+## Migrating From `sentry_flutter` `9.x` to `sentry_flutter` `10.x`
+
+See the [v9 to v10 migration guide](/platforms/dart/guides/flutter/migration/v9-to-v10/) for all changes, or use the [interactive migration checklist](/platforms/dart/guides/flutter/migration/v9-to-v10/interactive/) to track your progress.
+
 ## Migrating from `sentry_flutter` `8.x` to `sentry_flutter` `9.x`
 
 ### General
 
 #### Dart and Flutter versions
 
-The required minimum Dart and Flutter versions are now `3.5.0` and `3.24.0` respectively. 
+The required minimum Dart and Flutter versions are now `3.5.0` and `3.24.0` respectively.
 This change allows us to use safer APIs and better support for features such as Session Replay and WASM compilation.
 
 #### Android API version
@@ -18,7 +23,7 @@ The required minimum Android API is now `21`.
 
 #### API Removals and Renames
 
-- The `beforeScreenshot` method has been replaced by `beforeCaptureScreenshot`. 
+- The `beforeScreenshot` method has been replaced by `beforeCaptureScreenshot`.
 - Manual TTID implementation has been removed as the automatic TTID instrumentation has proven to be accurate enough so a manual one is not needed anymore.
 - `LoadImagesListIntegration` has been renamed to `LoadNativeDebugImagesIntegration`.
 - The `enableTracing` option has been removed. Use `options.traceSampleRate` or `options.tracesSampler` instead.
@@ -31,7 +36,7 @@ The required minimum Android API is now `21`.
 
 #### Response Body Handling
 
-Due to PII concerns, response bodies will no longer be added to Sentry events by the SDK automatically. 
+Due to PII concerns, response bodies will no longer be added to Sentry events by the SDK automatically.
 Responses are now attached to the `Hint` object, which can be read in `beforeSend`/`beforeSendTransaction` callbacks via `hint.response` so you can manually attach the response to your event.
 Response bodies with a size greater than 0.15MB are not added to the hint object.
 Currently as of version `9.0.0`, only the `dio` integration is supported.
@@ -44,12 +49,12 @@ Read the guide [here](/platforms/dart/guides/flutter/enriching-events/screenshot
 
 #### Logging
 
-The default log level is now `warning` when `debug = true`. 
+The default log level is now `warning` when `debug = true`.
 This can be adjusted by setting `options.diagnosticLevel = SentryLevel.info` in `SentryFlutter.init`.
 
 #### SDK Data Classes
 
-SDK data classes are now mutable which makes it easier to manipulate them. 
+SDK data classes are now mutable which makes it easier to manipulate them.
 For backwards-compatibility, `copyWith` and `clone` can still be used but are officially deprecated.
 
 ```dart
@@ -68,7 +73,7 @@ options.beforeSend = (event, hint) {
 
 ### Flutter Desktop
 
-Native crash handling is now enabled by default for Flutter Desktop. 
+Native crash handling is now enabled by default for Flutter Desktop.
 Windows ARM64 uses [breakpad](https://chromium.googlesource.com/breakpad/breakpad) and all other desktop platforms use [crashpad](https://chromium.googlesource.com/crashpad/crashpad).
 You can disable this feature by setting the `SENTRY_NATIVE_BACKEND` environment variable to "none". e.g `export SENTRY_NATIVE_BACKEND=none`
 

docs/platforms/dart/guides/flutter/migration/v9-to-v10/index.mdx

@@ -0,0 +1,87 @@
+---
+title: Migrate from 9.x to 10.x
+sidebar_order: 1
+description: "Learn how to migrate your Flutter application from Sentry SDK 9.x to 10.x."
+---
+
+<Include name="flutter-v10-agent-migration" />
+
+<Include name="flutter-v10-migration-overview" />
+
+<Alert title="Prefer a checklist?" level="info">
+
+The [Interactive v10 Migration Guide](./interactive/) lets you check off completed migration steps.
+
+</Alert>
+
+## Minimum Supported Versions
+
+<Include name="migration/flutter-v10/minimum-versions" />
+
+## Update Sentry Packages
+
+<Include name="migration/flutter-v10/sentry-packages" />
+
+## Android Builds Use Flutter's Kotlin Support
+
+<Include name="migration/flutter-v10/android-kotlin" />
+
+## Apple Builds Use Swift Package Manager
+
+<Include name="migration/flutter-v10/apple-swift-package-manager" />
+
+## Logs and Metrics Are Always Enabled
+
+<Include name="migration/flutter-v10/logs-and-metrics" />
+
+## Telemetry Callbacks Receive a Hint
+
+<Include name="migration/flutter-v10/telemetry-callbacks" />
+
+## Stream Mode Is the Default
+
+<Include name="migration/flutter-v10/stream-default" />
+
+## App Start Is a Standalone Trace
+
+<Include name="migration/flutter-v10/app-start" />
+
+## Native Failed Requests Are Opt-In
+
+<Include name="migration/flutter-v10/native-failed-requests" />
+
+## Profiling and Deprecated APIs Are Removed
+
+<Include name="migration/flutter-v10/removed-apis" />
+
+## Feature Flags Use the Current Scope
+
+<Include name="migration/flutter-v10/feature-flags" />
+
+## Span Attribute Names Have Changed
+
+<Include name="migration/flutter-v10/span-attributes" />
+
+## Throwing Callbacks Drop Telemetry
+
+<Include name="migration/flutter-v10/callback-failures" />
+
+## Error Processing and Release Health
+
+<Include name="migration/flutter-v10/error-processing" />
+
+## HTTP Error Capture and Grouping
+
+<Include name="migration/flutter-v10/http-error-capture" />
+
+## Sensitive Content Masking
+
+<Include name="migration/flutter-v10/sensitive-content" />
+
+## Desktop Crash Reporting Uses Breakpad
+
+<Include name="migration/flutter-v10/desktop-crash-reporting" />
+
+## Flutter Web Uses JavaScript SDK v11
+
+<Include name="migration/flutter-v10/flutter-web" />

docs/platforms/dart/guides/flutter/migration/v9-to-v10/interactive.mdx

@@ -0,0 +1,23 @@
+---
+title: Interactive v10 Migration Guide
+sidebar_order: 1
+description: "Migrate from Sentry Flutter SDK 9.x to 10.x with an interactive checklist."
+---
+
+<Include name="flutter-v10-agent-migration" />
+
+<Include name="flutter-v10-migration-overview" />
+
+This checklist covers the Flutter v10 migration. Some steps only apply to specific target platforms, integrations, or configuration options. Check off a step after completing it or confirming that it doesn't apply to your app. Your progress is saved in this browser.
+
+For details about each change, see the [migration guide](../).
+
+<Alert level="warning">
+
+The Dart analyzer won't catch every behavior change. Read through the steps before upgrading, including changes to telemetry defaults, error grouping, and release health.
+
+</Alert>
+
+## Your Migration Steps
+
+<MigrationGuide migration="flutter-v10" />

includes/flutter-v10-agent-migration.mdx

@@ -0,0 +1,5 @@
+<AgentMigrationCallout
+  guideUrl="/platforms/dart/guides/flutter/migration/v9-to-v10.md"
+  prompt="Upgrade this project from Sentry Flutter SDK v9 to v10. Inspect its Sentry packages and integrations, Dart and Flutter versions, target platforms, build configuration, and SDK initialization. Apply every migration step that applies to this project. Preserve the intended telemetry collection and privacy behavior, including logging integration defaults, native failed-request capture, and Flutter web sendDefaultPii. Review Apple Swift Package Manager setup, app-start tracing, callback failures, and desktop crash reporting where applicable. Use the project's package manager to update dependencies and its existing analysis, tests, and platform build checks to verify the migration. Summarize the changes and any remaining manual steps."
+  description="Copy this prompt into your AI agent to migrate to v10."
+/>

includes/flutter-v10-migration-overview.mdx

@@ -0,0 +1,11 @@
+Version 10 raises the minimum supported platform versions, removes deprecated APIs, and changes several telemetry defaults. The biggest changes are:
+
+- **Platform and build requirements:** Dart 3.12 and Flutter 3.44 are the new minimums, along with Android API 26, iOS 15, and macOS 12. Apple builds use Swift Package Manager instead of CocoaPods, and Android builds use Flutter's Kotlin support.
+- **API removals:** Profiling and deprecated APIs, including `copyWith` and `SentryFeedbackWidget`, are removed. Logs and metrics no longer need enable flags.
+- **Telemetry behavior:** The logging integration forwards Sentry logs by default, native failed-request capture becomes opt-in, and throwing filtering callbacks drop the affected telemetry.
+- **Tracing:** Stream mode is now the default. Migrate custom transaction instrumentation, filtering callbacks, and samplers, or explicitly select `SentryTraceLifecycle.static` to retain transaction mode.
+- **App-start tracing:** App start is a standalone `app.start` trace with its own sampling decision and a revised frame-span breakdown. Review custom sampling rules, dashboards, and alerts.
+- **Desktop crash reporting:** Windows and Linux default to Breakpad, with native crash reports uploaded after an application restart. A build-time override retains Crashpad.
+- **Flutter web:** The bundled JavaScript SDK moves to v11, and browser sessions report unhandled errors as `unhandled` rather than `crashed`. Flutter's `sendDefaultPii` option remains supported.
+
+The guide includes core Dart SDK changes that affect Flutter applications.

includes/migration/flutter-v10/android-kotlin.mdx

@@ -0,0 +1,12 @@
+---
+id: android-kotlin
+title: "Android Builds Use Flutter's Kotlin Support"
+phase: prerequisites
+category: version-support
+severity: action-required
+frameworks: all
+platformCategory: all
+order: 30
+---
+
+The Sentry Flutter plugin no longer applies or bundles its own Kotlin Gradle Plugin. It relies on Flutter 3.44's Kotlin support. If you customize Android build configuration, update it for Flutter 3.44 rather than relying on Sentry to supply Kotlin. This change does not require upgrading your app to AGP 9.

includes/migration/flutter-v10/app-start.mdx

@@ -0,0 +1,28 @@
+---
+id: app-start
+title: "App Start Is a Standalone Trace"
+phase: code-changes
+category: behavior
+severity: action-required
+frameworks: all
+platformCategory: all
+order: 70
+---
+
+On Android and iOS, app start is now reported as its own `app.start` root when tracing is enabled. It is no longer attached to the initial `ui.load` transaction and has its own sampling decision.
+
+Remove `options.enableStandaloneAppStartTracing` assignments. The standalone path is now the default, and the option has been removed. Update custom sampling rules, dashboards, and alerts that assume app start belongs to the first navigation transaction. A sampler that only accepts `ui.load` roots may exclude app start.
+
+If startup work continues past the first frame, call `SentryFlutter.extendAppStart()` before the first frame renders and `await SentryFlutter.finishExtendedAppStart()` when that work finishes. An extension that reaches the 30-second app-start deadline is dropped, and the reported duration falls back to the first frame.
+
+The app-start breakdown also changes in v10. Update queries, dashboards, and `beforeSendSpan` callbacks that match `app.start.plugin_registration`, `app.start.sentry_setup`, or `app.start.first_frame_render`. These operations are no longer emitted. The SDK records measured startup work using:
+
+| Operation                          | Measured Work                                 |
+| ---------------------------------- | --------------------------------------------- |
+| `app.start.root_widget_attachment` | Attachment of the root widget                 |
+| `app.start.frame_build`            | Flutter framework frame builds during startup |
+| `app.start.frame_raster`           | Rasterization of the first frame              |
+
+These spans are not one-to-one replacements for the previous broad intervals. Frame-build spans include `flutter.frame.warm_up` and `flutter.frame.deferred` attributes. A frame-build span does not by itself mean that the frame was submitted to the engine or displayed.
+
+Startup frame builds that begin at or after the first frame's rasterization starts are also excluded.

includes/migration/flutter-v10/apple-swift-package-manager.mdx

@@ -0,0 +1,23 @@
+---
+id: apple-swift-package-manager
+title: "Apple Builds Use Swift Package Manager"
+phase: prerequisites
+category: package
+severity: action-required
+frameworks: all
+platformCategory: all
+order: 40
+---
+
+The Sentry Flutter plugin no longer supports CocoaPods. On iOS and macOS, it uses Swift Package Manager to install the native Sentry Cocoa SDK, which has been upgraded to v9. If you initialize Sentry separately in native code or call its Swift/Objective-C APIs directly, also review the [Sentry Cocoa v8-to-v9 migration guide](/platforms/apple/migration/v8-to-v9/).
+
+Flutter 3.44 enables Swift Package Manager by default and migrates your project when you run the app. If you previously disabled it, re-enable it and remove any project-level `enable-swift-package-manager: false` setting:
+
+```bash
+flutter config --enable-swift-package-manager
+flutter pub get
+```
+
+Set the iOS and macOS deployment targets in Xcode to the minimum versions listed in [Minimum Supported Versions](/platforms/dart/guides/flutter/migration/v9-to-v10/#minimum-supported-versions). For custom targets, flavors, or projects that don't migrate automatically, follow [Flutter's Swift Package Manager migration instructions](https://docs.flutter.dev/packages-and-plugins/swift-package-manager/for-app-developers/).
+
+Other Flutter plugins may still require CocoaPods. Only remove your application's CocoaPods integration once all of its dependencies support Swift Package Manager.

includes/migration/flutter-v10/callback-failures.mdx

@@ -0,0 +1,16 @@
+---
+id: callback-failures
+title: "Throwing Callbacks Drop Telemetry"
+phase: code-changes
+category: behavior
+severity: behavior-change
+frameworks: all
+platformCategory: all
+order: 115
+---
+
+In v10, an exception in an event processor or a filtering callback drops the affected telemetry item instead of sending the item through unchanged.
+
+This applies to event processors, `beforeSend`, `beforeSendTransaction`, `beforeSendFeedback`, `beforeBreadcrumb`, `beforeSendLog`, and `beforeSendMetric`. Review callbacks that can throw, especially custom filtering and scrubbing logic. Handle expected failures inside the callback and return the intended item or `null` explicitly.
+
+In transaction mode, a throwing `tracesSampler` uses the inherited sampling decision when available, then falls back to `tracesSampleRate`. In stream mode, it falls back to `tracesSampleRate`. Do not rely on throwing an exception to reject a trace; return `0.0` to reject it explicitly.

includes/migration/flutter-v10/desktop-crash-reporting.mdx

@@ -0,0 +1,27 @@
+---
+id: desktop-crash-reporting
+title: "Desktop Crash Reporting Uses Breakpad"
+phase: verify
+category: behavior
+severity: behavior-change
+frameworks: all
+platformCategory: all
+order: 150
+---
+
+On Windows and Linux, the default native crash backend changes to Breakpad. Native crash reports are uploaded when the application starts again, rather than by a separate Crashpad handler at crash time.
+
+Breakpad handles crashes in the application process, without Crashpad's out-of-process isolation. It also lacks Crashpad's Windows Error Reporting (WER) and fast-fail coverage. Review crash-delivery expectations and test a crash followed by an application restart.
+
+To retain Crashpad, set the `SENTRY_NATIVE_BACKEND` environment variable to `crashpad` in your local build environment and CI before building the application. For example:
+
+```bash {tabTitle:Linux} {mdExpandTabs}
+SENTRY_NATIVE_BACKEND=crashpad flutter build linux
+```
+
+```powershell {tabTitle:Windows}
+$env:SENTRY_NATIVE_BACKEND = "crashpad"
+flutter build windows
+```
+
+This is a build-time setting, not a Dart SDK initialization option.

includes/migration/flutter-v10/error-processing.mdx

@@ -0,0 +1,16 @@
+---
+id: error-processing
+title: "Error Processing and Release Health"
+phase: verify
+category: behavior
+severity: behavior-change
+frameworks: all
+platformCategory: all
+order: 120
+---
+
+Error sampling through `sampleRate` now happens after event processors and `beforeSend`. These callbacks run even for events that are subsequently sampled out, so review callbacks that perform expensive work or have side effects. An event dropped by `beforeSend` is reported as a `before_send` discard rather than a `sample_rate` discard.
+
+On Android, iOS, and macOS, unhandled Flutter errors now mark sessions as unhandled rather than crashed. Unhandled errors dropped by `sampleRate` also affect release health. Review release-health comparisons across the upgrade because session classification and sampling behavior have changed.
+
+For the web session-status change, see [Flutter Web Uses JavaScript SDK v11](/platforms/dart/guides/flutter/migration/v9-to-v10/#flutter-web-uses-javascript-sdk-v11).

includes/migration/flutter-v10/feature-flags.mdx

@@ -0,0 +1,14 @@
+---
+id: feature-flags
+title: "Feature Flags Use the Current Scope"
+phase: code-changes
+category: removed-api
+severity: action-required
+frameworks: all
+platformCategory: all
+order: 100
+---
+
+Feature flag evaluations now belong to the current hub and scope, rather than `FeatureFlagsIntegration`. If you accessed that integration directly, replace those calls with `await Sentry.addFeatureFlag('flag-name', true)`.
+
+Existing calls to `Sentry.addFeatureFlag` continue to work. Custom `Hub` implementations must implement `addFeatureFlag(String flag, bool result)`.

includes/migration/flutter-v10/flutter-web.mdx

@@ -0,0 +1,20 @@
+---
+id: flutter-web
+title: "Flutter Web Uses JavaScript SDK v11"
+phase: verify
+category: behavior
+severity: behavior-change
+frameworks: all
+platformCategory: all
+order: 160
+---
+
+Flutter web now bundles Sentry JavaScript SDK `11.0.0`. Browser sessions affected by unhandled errors are reported as `unhandled` rather than `crashed`. On web, `unhandled` is a terminal session status; native sessions treat unhandled Flutter errors as non-terminating.
+
+For errors captured through the Dart SDK, web sessions are updated only after error sampling. Errors dropped by `sampleRate` do not update web release health.
+
+Review web release-health dashboards and alerts that depend on crashed-session counts. This applies to unhandled errors captured from both Dart and JavaScript.
+
+Keep using Flutter's `options.sendDefaultPii`. The Flutter SDK maps it to JavaScript v11's `dataCollection` settings and preserves the previous JavaScript privacy baseline when `sendDefaultPii` is `false`. You do not need to replace the Flutter option with a JavaScript configuration object.
+
+If you initialize Sentry separately in JavaScript or call its APIs directly, also review the [JavaScript v10-to-v11 migration guide](/platforms/javascript/migration/v10-to-v11/).

includes/migration/flutter-v10/http-error-capture.mdx

@@ -0,0 +1,20 @@
+---
+id: http-error-capture
+title: "HTTP Error Capture and Grouping"
+phase: verify
+category: behavior
+severity: behavior-change
+frameworks: all
+platformCategory: all
+order: 130
+---
+
+HTTP error types, messages, and capture rules have changed. Review HTTP error filters, grouping rules, and alert volumes after upgrading:
+
+- `SentryHttpClient` reports failed HTTP status responses with the stable exception type `SentryHttpClientError`, and its message no longer starts with `Exception:`.
+- `sentry_dio` uses the stable exception type `DioException`, including in obfuscated builds. Default error messages become `HTTP Client Error with status code: <code>` or `HTTP Client Error: <failure>`. Custom Dio string builders are preserved.
+- `sentry_dio` now captures connection failures without a status code, such as timeouts, DNS failures, and certificate errors, when failed-request capture is enabled and the target matches. Caller-initiated cancellations without a status code are excluded.
+- `sentry_dio` matches `failedRequestTargets` against the resolved full URL instead of the relative request path. Update patterns that assumed a path-only value.
+- `sentry_supabase` uses the stable exception type `SentrySupabaseClientError`, and its message no longer starts with `Exception:`.
+
+Dio events now include response status and metadata in `event.contexts.response`; response bodies remain on `hint.response`. Failed-request capture through `SentryHttpClient` and Dio excludes requests to the configured DSN host to prevent recursive error reporting.