feat(span-first): Port native app start integration to V2 span API

[buenaflor]

📜 Description

Ports the native app start and generic app start integrations to the V2 streaming span API, gated by SentryTraceLifecycle.streaming.

💡 Motivation and Context

Span-first and closes #3334

💚 How did you test it?

Unit tests, manual tests

📝 Checklist

• I reviewed submitted code
• I added tests to verify changes
• No new PII added or SDK only sends newly added PII if sendDefaultPii is enabled
• I updated the docs if needed
• All tests passing
• No breaking changes

🔮 Next steps

Make sure mobile vitals insights product page works

#skip-changelog

[github-actions]

🚨 Detected changes in high risk code 🚨

High-risk code has higher potential to break the SDK and may be hard to test. To prevent severe bugs, apply the rollout process for releasing such changes and be extra careful when changing and reviewing these files:

• packages/flutter/lib/src/integrations/native_app_start_integration.dart

[github-actions]

	Messages
📖	Do not forget to update Sentry-docs with your feature once the pull request gets approved.

Generated by 🚫 dangerJS against d11c441

[buenaflor]

pull out the common things we can to share logic with native app start handler v2 and v1

[Copilot]

Pull request overview

Ports native + generic app-start instrumentation and time-to-display navigation spans to the V2 “streaming” span API, gated by SentryTraceLifecycle.streaming, to support span-first auto-instrumentation.

Changes:

• Adds root-navigation preparation/tracking APIs to TimeToDisplayTrackerV2 and updates navigation observer to use trackNonRootNavigation.
• Introduces NativeAppStartHandlerV2 (streaming) and factors native app-start parsing into shared native_app_start_data.dart.
• Extends Hub V2 span creation APIs to support startTimestamp, with updated mocks and tests.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/flutter/lib/src/navigation/time_to_display_tracker_v2.dart	Adds root navigation preparation + tracking and a dedicated non-root tracking API for streaming spans.
packages/flutter/lib/src/navigation/sentry_navigator_observer.dart	Switches streaming navigation tracking to trackNonRootNavigation.
packages/flutter/lib/src/integrations/native_app_start_integration.dart	Routes native app-start handling to V2 handler when traceLifecycle == streaming and prepares root navigation early.
packages/flutter/lib/src/integrations/native_app_start_handler_v2.dart	New streaming handler creating app-start phase spans as V2 spans under a prepared root span.
packages/flutter/lib/src/integrations/native_app_start_handler.dart	Reuses shared native app-start parsing via parseNativeAppStart.
packages/flutter/lib/src/integrations/native_app_start_data.dart	New shared parsing/validation types for native app-start timing.
packages/flutter/lib/src/integrations/generic_app_start_integration.dart	Uses trackRootNavigation() in streaming mode instead of creating a V1 transaction.
packages/flutter/lib/src/sentry_flutter.dart	Wires NativeAppStartHandlerV2 into SDK init integration setup.
packages/flutter/test/navigation/time_to_display_tracker_v2_test.dart	Updates/extends tracker tests for root vs non-root navigation and preparation behavior.
packages/flutter/test/navigation/sentry_navigator_observer_test.dart	Updates streaming observer tests to expect non-root navigation tracking calls.
packages/flutter/test/navigation/fake_time_to_display_tracker_v2.dart	Updates fake tracker to match new API/return type.
packages/flutter/test/integrations/native_app_start_integration_test.dart	Updates integration fixture to provide a V2 native app-start handler.
packages/flutter/test/integrations/native_app_start_handler_v2_test.dart	New unit tests covering V2 native app-start span creation/backdating/origins.
packages/flutter/test/integrations/generic_app_start_integration_test.dart	Adds streaming-mode coverage for generic app start using V2 spans.
packages/flutter/test/mocks.mocks.dart	Regenerated mocks to include new startTimestamp params/defaults.
packages/flutter/example/lib/main.dart	Updates example to demonstrate custom span work during app start then report fully displayed.
packages/dart/lib/src/hub.dart	Adds startTimestamp support to startInactiveSpan/startIdleSpan and passes it into span constructors.
packages/dart/lib/src/hub_adapter.dart	Threads startTimestamp through adapter methods.
packages/dart/lib/src/noop_hub.dart	Updates NoOpHub signatures to accept startTimestamp.
packages/dart/lib/src/telemetry/span/recording_sentry_span_v2.dart	Adds startTimestamp support in constructors and an internal setter for backdating.
packages/dart/lib/src/telemetry/span/idle_recording_sentry_span_v2.dart	Threads startTimestamp into idle span construction.
packages/dart/test/hub_span_test.dart	Adds test coverage for startTimestamp behavior on inactive + idle spans.

Comments suppressed due to low confidence (1)

packages/flutter/lib/src/navigation/time_to_display_tracker_v2.dart:183

• The new docstring says this "cancels all spans for the current route", but the implementation cancels any active idle span on the hub (including idle spans not created by this tracker, e.g. user-interaction idle spans). Consider tightening the wording or scoping the cancellation to only spans created/prepared by this tracker.

  /// Cancels all spans for the current route and resets tracker state.
  void cancelCurrentRoute() {
    _ttfdSpan = null;
    _preparedRootNavigationSpan = null;

    final activeSpan = _hub.getActiveSpan();
    if (activeSpan is IdleRecordingSentrySpanV2) {
      activeSpan
        ..status = SentrySpanStatusV2.cancelled
        ..end();
    }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[buenaflor]

@cursor review

[buenaflor]

@sentry review

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[buenaflor]

spec is still tbd

[buenaflor]

realistically won't happen but let's assert so it shows up in debug at least as an error

[denrase]

Added some more context to the questions, feel free to pick up if they make sense.