fix(app): migrate flutter_contacts to 2.x — 1.x crashes under UIScene

[formed2forge]

Why

flutter_contacts 1.1.9+2's iOS registration force-unwraps UIApplication.shared.delegate!.window!!.rootViewController!, which is nil under the UIScene lifecycle (#11568) and crashes with EXC_BREAKPOINT on launch. Plugin registration is alphabetical and synchronous (GeneratedPluginRegistrant.m), so this crash takes down every alphabetically later plugin too — SharedPreferences, Sqflite, PermissionHandler, Geolocator, WebView, ~27 in total. Confirmed via full crash backtrace on iPhone 17 Pro / iOS 27.0 while verifying the UIScene migration.

What changed

No 1.x patch exists past 1.1.9+2 — checked the full pub.dev version list. The fix only landed in 2.x, a complete Dart-API rewrite. Migrated the 3 call sites:

• requestPermission({readonly}) → bool becomes permissions.request(PermissionType.read|readWrite) → PermissionStatus (granted/limited stand in for the old true).
• getContacts(withProperties: true, withPhoto: false) becomes getAll(properties: {ContactProperty.phone}) — narrower and cheaper, since these call sites only ever read phones/displayName, and those two are always fetched regardless of the requested property set.
• Contact.displayName: non-null String → nullable String? in 2.x.
• Phone.label: bare PhoneLabel enum → Label<PhoneLabel> wrapper; phone.label.name → phone.label.label.name.

phone_calls_page.dart and phone_call_provider.dart both already import permission_handler, which also exports a type named PermissionStatus — writing flutter_contacts' bare PermissionStatus in either file is an ambiguous-import error. Fixed with hide PermissionStatus on the permission_handler import in both files; neither file spells that package's own PermissionStatus by name anywhere, so nothing else changes.

Bonus: 2.3.1 ships a Package.swift, so flutter_contacts drops off the "doesn't support Swift Package Manager" warning Flutter prints on every iOS build.

Verification

flutter analyze: 0 errors on the 3 changed files (1 pre-existing unrelated lint), 0 new errors project-wide. Combined with the UIScene migration (#11570) and a Firebase local-config fix (separate PR) on a throwaway community-build test, the app reached the sign-in screen on iPhone 17 Pro / iOS 27.0, confirmed visually — the first time this plugin registration chain has completed under UIScene on this project.

No dedicated regression test: there's no way to unit-test a native UIScene-launch crash without device access. The version constraint itself (commented in pubspec.yaml) is the guard — a downgrade to 1.x would silently reintroduce the crash.

Failure-Class: none

[cubic-dev-ai]

2 issues found across 5 files

Confidence score: 2/5

• In app/lib/pages/conversation_detail/widgets/share_to_contacts_sheet.dart, the read-only contact picker requests WRITE_CONTACTS alongside READ_CONTACTS on Android, and because only READ_CONTACTS is declared the permission flow can fail and block contact loading for users — request only READ_CONTACTS for this path (or declare/write-gate WRITE_CONTACTS where truly needed).
• In app/lib/pages/phone_calls/phone_calls_page.dart, using phone.label.label.name can show the enum token (custom) instead of the user’s real custom label, which degrades contact clarity in call UI — read the display value from customLabel when the label type is custom.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="app/lib/pages/conversation_detail/widgets/share_to_contacts_sheet.dart">

<violation number="1" location="app/lib/pages/conversation_detail/widgets/share_to_contacts_sheet.dart:78">
P1: On Android, this read-only flow requests `WRITE_CONTACTS` in addition to `READ_CONTACTS`, but the app declares only `READ_CONTACTS`. The request therefore returns denied and prevents users from loading contacts; request `PermissionType.read` instead.</violation>
</file>

<file name="app/lib/pages/phone_calls/phone_calls_page.dart">

<violation number="1" location="app/lib/pages/phone_calls/phone_calls_page.dart:284">
P3: For phones with custom labels, `phone.label.label.name` renders the literal enum name ('custom') instead of the contact's actual label. Since `Label<PhoneLabel>` carries the display text in `customLabel`, prefer reading it so custom-labeled numbers show the real label (e.g. 'Business') rather than the generic 'custom'. This preserves the prior 1.x string, but the migrated accessor is the place to use the richer value.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: On Android, this read-only flow requests WRITE_CONTACTS in addition to READ_CONTACTS, but the app declares only READ_CONTACTS. The request therefore returns denied and prevents users from loading contacts; request PermissionType.read instead.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At app/lib/pages/conversation_detail/widgets/share_to_contacts_sheet.dart, line 78:

<comment>On Android, this read-only flow requests `WRITE_CONTACTS` in addition to `READ_CONTACTS`, but the app declares only `READ_CONTACTS`. The request therefore returns denied and prevents users from loading contacts; request `PermissionType.read` instead.</comment>

<file context>
@@ -75,7 +75,8 @@ class _ShareToContactsBottomSheetState extends State<ShareToContactsBottomSheet>
 
     // Request contacts permission using flutter_contacts' own method
-    final permissionGranted = await FlutterContacts.requestPermission();
+    final status = await FlutterContacts.permissions.request(PermissionType.readWrite);
+    final permissionGranted = status == PermissionStatus.granted || status == PermissionStatus.limited;
 
</file context>

Suggested change

	final status = await FlutterContacts.permissions.request(PermissionType.readWrite);
	final status = await FlutterContacts.permissions.request(PermissionType.read);

[cubic-dev-ai]

P3: For phones with custom labels, phone.label.label.name renders the literal enum name ('custom') instead of the contact's actual label. Since Label<PhoneLabel> carries the display text in customLabel, prefer reading it so custom-labeled numbers show the real label (e.g. 'Business') rather than the generic 'custom'. This preserves the prior 1.x string, but the migrated accessor is the place to use the richer value.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At app/lib/pages/phone_calls/phone_calls_page.dart, line 284:

<comment>For phones with custom labels, `phone.label.label.name` renders the literal enum name ('custom') instead of the contact's actual label. Since `Label<PhoneLabel>` carries the display text in `customLabel`, prefer reading it so custom-labeled numbers show the real label (e.g. 'Business') rather than the generic 'custom'. This preserves the prior 1.x string, but the migrated accessor is the place to use the richer value.</comment>

<file context>
@@ -276,11 +278,12 @@ class _PhoneCallsPageState extends State<PhoneCallsPage> with SingleTickerProvid
-                      initial: contact.displayName.isNotEmpty ? contact.displayName[0].toUpperCase() : '?',
-                      onCall: () => _makeCall(phone.number, contactName: contact.displayName),
+                      name: name,
+                      phone: '${phone.label.label.name} ${phone.number}',
+                      initial: name.isNotEmpty ? name[0].toUpperCase() : '?',
+                      onCall: () => _makeCall(phone.number, contactName: name),
</file context>

[kodjima33]

flutter_contacts 1.x force-unwraps rootViewController and takes down the whole plugin registration chain under UIScene; 2.x migration is the only fix, and all 3 call sites are migrated correctly.