Update Quickstart for Flutter/Dart to v5

[Aaron LaBeau (biozal)]

Summary

Migrates the Flutter flutter_quickstart app from ditto_live 4.13.1 to 5.0.0,
along with the API surface, platform configuration, dependency, and test
changes that the v5 upgrade requires. Also pins the toolchain via fvm and
modernises the surrounding lint/dependency stack.

Highlights

• New DittoConfig / Ditto.open(config) API replaces the deprecated
  OnlinePlaygroundIdentity flow.
• New ditto.sync.* namespace replaces top-level startSync / stopSync /
  isSyncActive.
• All DQL UPDATE statements now use parameterised arguments instead of
  string interpolation — eliminates a DQL-injection vector via task titles.
• iOS now runs as a true background BLE peer (background modes added) with a
  raised deployment target of iOS 15.6.
• Widget tests rewritten from the empty Flutter "counter" stub into 8 real
  tests covering the Task model and AddTaskDialog.
• Integration-test reliability fix: native iOS permission alerts are now
  auto-dismissed at the XCTest layer via addUIInterruptionMonitor, and the
  cloud-sync wait was converted from a fixed 5 s sleep to a 45 s poll.

Dependency changes (pubspec.yaml)

Package	Before	After	Notes
ditto_live	4.13.1	5.0.0	Headline upgrade (was through RC1/3)
permission_handler	^11.3.1	^12.0.1	Required for v5 BLE permission flow
flutter_dotenv	^5.1.0	^6.0.0	Resolves to 6.0.1
flutter_lints	^4.0.0	^6.0.0	Pulls lints 5.1.1 → 6.1.0

Toolchain & repo

• Added .fvmrc pinning Flutter to 3.32.8 so CI and contributors run
  the same toolchain.
• .gitignore: ignore .fvm/ cache.

Source changes (lib/)

lib/main.dart — v5 API migration

• OnlinePlaygroundIdentity(...) + Ditto.open(identity: ...) →
  DittoConfig(databaseID, connect: DittoConfigConnectServer(url:)) +
  Ditto.open(config).
• New auth model: ditto.auth.setExpirationHandler + ditto.auth.login(token, provider: developmentProvider).
• ditto.startSync() / stopSync() / isSyncActive →
  ditto.sync.start() / sync.stop() / sync.isActive.
• ditto.sync.registerSubscription("SELECT * FROM tasks WHERE deleted = false")
  is now registered before sync.start() so the subscription is
  included in the very first sync exchange (eliminates a 5–10 s first-sync
  delay).
• Removed updateTransportConfig(...) (replaced by DittoConfig).
• Removed the ALTER SYSTEM SET DQL_STRICT_MODE = false workaround.
• Enabled debug logging via DittoLogger.isEnabled = true /
  minimumLogLevel = LogLevel.debug.
• DITTO_AUTH_URL is now required — throws on missing env, matching the
  other env vars.

lib/main.dart — DQL injection hardening

All three UPDATE calls converted from string-interpolated DQL to bound
arguments:

| Operation | Before | After
|
|-----------------|-------------------------------------------------------------|-------------------------------------------------------------------------------------------------
-|
| Soft-delete | UPDATE tasks SET deleted = true WHERE _id = '${task.id}' | UPDATE tasks SET deleted = true WHERE _id = :id, arguments: {"id": task.id}
|
| Toggle done | UPDATE tasks SET done = $value WHERE _id = '${task.id}' | UPDATE tasks SET done = :done WHERE _id = :id, arguments: {"done": value, "id": task.id}
|
| Edit title | UPDATE tasks SET title = '${newTask.title}' where _id ... | UPDATE tasks SET title = :title WHERE _id = :id, arguments: {"title": ..., "id": ...}
|

lib/dialog.dart

• Added dispose() to release the TextEditingController (was being leaked
  per dialog open).

iOS

• ios/Runner/Info.plist
  • Added UIBackgroundModes with bluetooth-central and
    bluetooth-peripheral — required by Ditto v5 for BLE sync to operate
    in the background.
  • Fixed indent on the existing _http-alt._tcp. Bonjour service entry.
• ios/Runner.xcodeproj/project.pbxproj
  • Set IPHONEOS_DEPLOYMENT_TARGET = 15.6 across all three build configs
    (Debug / Release / Profile) to match the v5 SDK floor.
• ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme
  • Wires customLLDBInitFile = $(SRCROOT)/Flutter/ephemeral/flutter_lldbinit
    for both Test and Launch actions (modern Flutter LLDB integration).
  • Launch action default flipped from Release to Debug.
• ios/RunnerTests/RunnerTests.m — see Tests below.

macOS

• macos/Podfile: platform :osx, '10.14' → '12.0' (v5 minimum).
• macos/Runner/DebugProfile.entitlements: added
  com.apple.security.network.client = true so debug builds can establish
  outbound sync connections under App Sandbox.

Windows

windows/CMakeLists.txt:

Setting	Before	After
MSVC warning level	/W4	/W5
_HAS_EXCEPTIONS	0	1
CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD	1	2

(C++ exceptions are now allowed because v5's Windows binding requires them;
warning bump is opportunistic.)

Tests

test/widget_test.dart — rewritten

Old file was the unmodified Flutter "counter" smoke test (which couldn't run
because it tried to construct DittoExample against real env vars). Replaced
with 8 hermetic tests covering pieces that don't need a live Ditto
instance:

• Task model: fromJson, toJson, null-id omission, roundtrip.
• Add task dialog: title shown for new vs. edit, cancel returns null,
  submit returns a Task.

integration_test/app_test.dart

native `UIAlertController`s and unreachable from the Flutter widget tree.                          
Permission handling moved to the XCTest layer (below).                                                                                                                          

• pumpAndSettle window for first-sync widened from 5 s → 10 s.
• The fixed Future.delayed(5s) plus single expect for the test document
  was replaced with a 500 ms poll up to a 45 s deadline, which fixes
  flakiness on slow BrowserStack devices and busy playground tenants.

ios/RunnerTests/RunnerTests.m — replaced macro with explicit suite

The one-line INTEGRATION_TEST_IOS_RUNNER(RunnerTests) macro was replaced
with a hand-written XCTestCase that adds a UIInterruptionMonitor in
-setUp. The monitor automatically taps OK / Allow /
Allow While Using App on any springboard alert that appears during the
run, so Bluetooth and Local Network permission dialogs no longer block
sync from initialising in CI.

CI

.github/browserstack-devices.yml: iPhone 13 entry bumped from iOS 15 → 16
to match the new IPHONEOS_DEPLOYMENT_TARGET = 15.6.

README

• "Tested on Flutter 3.24" → "Tested on 3.29 / 3.32".
• JVM 11 → "JVM 11 or greater".
• New Flutter Version Manager section pointing at fvm.app.
• New macOS Development section (Xcode 26.2 / macOS 26.6 / Flutter 3.29.3 & 3.32.8).
• New Windows Development section (VS 2022 + C++ + cmake).
• Added Homebrew alternative for installing CocoaPods.

Test plan

• fvm flutter pub get resolves cleanly on a fresh checkout.
• fvm flutter analyze — no issues.
• fvm flutter test — all 8 widget tests pass.
• fvm flutter run on an iOS device: app launches, accepts BT + Local
  Network permission, syncs a task created on a second device.
• fvm flutter run -d macos: app launches sandboxed, sync works.
• fvm flutter run -d windows: builds and runs against VS 2022.
• Integration test against BrowserStack iPhone 13 (iOS 16) passes
  end-to-end (permission monitor dismisses dialogs, polling finds
  TASK_TO_FIND within 45 s).
• Verify edited task titles containing ', ;, etc. no longer break
  UPDATE (parameterised args).

Risk / call-outs

• iOS deployment target raised to 15.6 — drops iOS 13/14/15.0–15.5.
  This matches Ditto v5's own floor, but flag it for any user still on
  those OS versions.
• macOS deployment target raised to 12.0 (from 10.14) for the same
  reason.
• DITTO_AUTH_URL is now required at startup; deployments that previously
  relied on a default will need to set it explicitly.

[Copilot]

Pull request overview

Updates the Flutter/Dart quickstart app to Ditto v5, including dependency upgrades, updated Ditto initialization/sync APIs, and more reliable integration testing (notably on iOS where native permission dialogs can block Flutter-driven UI tests).

Changes:

• Bump Flutter dependencies to Ditto v5 and update app code to the new Ditto config/auth/sync APIs.
• Improve widget/integration tests (iOS permission handling via XCTest interruption monitor; cloud-sync polling instead of fixed delays).
• Update platform/build configuration and developer tooling (iOS/macOS project settings, Windows CMake settings, FVM pinning, CI device matrix).

Reviewed changes

Copilot reviewed 15 out of 19 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
flutter_app/windows/CMakeLists.txt	Updates Windows build flags and Visual Studio install behavior.
flutter_app/test/widget_test.dart	Replaces default template test with model/dialog unit & widget tests.
flutter_app/README.md	Updates prerequisites/platform notes and iOS setup instructions.
flutter_app/pubspec.yaml	Upgrades Ditto + related Flutter/Dart dependencies and lints.
flutter_app/pubspec.lock	Regenerates lockfile for upgraded dependency set and SDK baselines.
flutter_app/macos/Runner/DebugProfile.entitlements	Adds macOS network client entitlement for sandboxed networking.
flutter_app/macos/Podfile.lock	Updates CocoaPods lock to Ditto v5 and related pod versions.
flutter_app/macos/Podfile	Raises macOS deployment target for plugin/toolchain compatibility.
flutter_app/lib/main.dart	Migrates Ditto init/config/sync usage to v5 and improves initial subscription timing.
flutter_app/lib/dialog.dart	Adds proper controller disposal to prevent leaks in dialog widget.
flutter_app/ios/RunnerTests/RunnerTests.m	Replaces macro runner to auto-accept iOS permission dialogs during tests.
flutter_app/ios/Runner/Info.plist	Adds background BLE modes required for Ditto BLE sync behavior.
flutter_app/ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme	Updates scheme config (debug launch, LLDB init file).
flutter_app/ios/Runner.xcodeproj/project.pbxproj	Sets iOS deployment target to 15.6 in multiple build configs.
flutter_app/ios/Podfile.lock	Updates iOS CocoaPods lock to Ditto v5 and related pod versions.
flutter_app/integration_test/app_test.dart	Makes integration test more resilient (longer settle, sync polling, iOS note).
.gitignore	Ignores FVM cache directory.
.github/browserstack-devices.yml	Updates BrowserStack iOS device targets to match new minimum iOS baseline.
.fvmrc	Pins Flutter toolchain version via FVM for reproducible builds.

---

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