fix: ensure FlutterResult and invokeMethod are always called on main thread (#98)

* fix: ensure FlutterResult and invokeMethod are always called on main thread

iOS 16 requires FlutterResult to be invoked on the main thread. When
OptimizelyClient.start() or decideAsync closures call result() from a
background thread under multi-SDK startup contention, iOS 16 silently
drops the response causing the Dart Future to never resolve or return
null, which previously crashed the app with an unhandled TypeError or
PlatformException.

Two layers fixed:

1. iOS native (SwiftOptimizelyFlutterSdkPlugin.swift)
   - Added mainThreadResult() private helper that wraps FlutterResult
     to always dispatch on the main thread (no-op if already on main)
   - Applied once in handle() so every current and future method handler
     is protected automatically — no per-handler changes needed

2. Dart layer (OptimizelyClientWrapper + OptimizelyUserContext)
   - Added _invoke() helper that wraps every MethodChannel.invokeMethod
     call with a null guard and PlatformException catch
   - Null response returns {success:false} instead of crashing via
     Map.from(null) → TypeError
   - PlatformException is caught and returned as {success:false}
   - All 18 call sites in OptimizelyClientWrapper and 14 in
     OptimizelyUserContext now route through _invoke

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* chore: update CLAUDE.md with expanded guidance and add IDE/env gitignore entries

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test: add unit tests for _invoke() null and PlatformException safety branches

Covers the two previously-uncovered error branches in the iOS 16 fix:
- Native returns null → success:false (no TypeError)
- Native throws PlatformException → success:false (no unhandled exception)

Tests both OptimizelyClientWrapper and OptimizelyUserContext.
Overall unit test coverage: 85.9% → 87.3%

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix: ensure MethodChannel.Result is always called on main thread (Android)

Mirrors the iOS mainThreadResult() fix. Added safeResult() wrapper in
onMethodCall() that dispatches success/error/notImplemented to the Android
main thread via Handler(Looper.getMainLooper()) when called from a
background thread. Applied once so all current and future handlers are
automatically protected.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix: use nullable-safe TestDefaultBinaryMessengerBinding access in tests

Flutter 3.0.5 (used in CI) exposes instance as nullable — use ?.
pattern consistent with existing test suite to fix compilation failure.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: muzahidul-opti

.gitignore

@@ -120,3 +120,8 @@ app.*.symbols
 !**/ios/**/default.perspectivev3
 !/packages/flutter_tools/test/data/dart_dependencies_test/**/.packages
 !/dev/ci/**/Gemfile.lock
+
+# Environment variables
+.env
+.mcp.json
+.claude/settings.local.json

CLAUDE.md

@@ -4,38 +4,26 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-Optimizely Flutter SDK - Cross-platform plugin wrapping native Optimizely SDKs (iOS, Android) for A/B testing, feature flags, CMAB, and ODP integration and others.
+Optimizely Flutter SDK - Cross-platform plugin wrapping native Optimizely SDKs (iOS, Android) for A/B testing, feature flags, CMAB, and ODP integration.
 
 **Main Branch:** master
 
-## Project Structure
-
-```
-lib/                        # Dart: Public API, data models, user context, platform bridge
-android/src/main/java/      # Java: OptimizelyFlutterClient.java, Plugin, helpers
-ios/Classes/                # Swift: Plugin, logger bridge, helpers
-test/                       # Unit tests (SDK, CMAB, logger, nested objects)
-example/                    # Example app
-```
-
 ## Essential Commands
 
 ```bash
 # Setup
 flutter pub get
+cd ios && pod install              # iOS dependencies
 
 # Testing
-flutter test                                    # All tests
-flutter test test/cmab_test.dart                # Specific test
-flutter test --coverage                         # With coverage
+flutter test                       # All tests
+flutter test test/cmab_test.dart   # Specific test
+flutter test --coverage            # With coverage
 
 # Linting
 flutter analyze
 
-# iOS setup
-cd ios && pod install
-
-# Run example
+# Run example app
 cd example && flutter run
 ```
 
@@ -47,9 +35,9 @@ Dart API (OptimizelyFlutterSdk)
     ↓
 Wrapper (OptimizelyClientWrapper) + MethodChannel
     ↓
-Native (Swift/Java plugin implementations)
+Native Plugins (Swift/Java)
     ↓
-Native Optimizely SDKs
+Native Optimizely SDKs (5.2.1 iOS / 5.1.1 Android)
 ```
 
 ### Critical Patterns
@@ -58,68 +46,151 @@ Native Optimizely SDKs
 - ALL methods return `BaseResponse` derivatives (never throw exceptions)
 - Check `success` boolean and `reason` string for errors
 
-**2. Multi-Instance State**
+**2. Multi-Instance State Management**
 - SDK instances tracked by `sdkKey`
 - User contexts: `sdkKey → userContextId → context`
 - Notification listeners: `sdkKey → listenerId → callback`
 - Call `close()` for cleanup
 
-**3. Platform-Specific Type Encoding**
+**3. Platform-Specific Type Encoding (CRITICAL)**
 - **iOS**: Attributes need type metadata: `{"value": 123, "type": "int"}`
 - **Android**: Direct primitives: `{"attribute": 123}`
-- Conversion in `convertToTypedMap()` (`optimizely_client_wrapper.dart`)
-
-**4. Dual Channels**
-- `optimizely_flutter_sdk` - Main API
-- `optimizely_flutter_logger` - Native log forwarding
-
-## Key Files
-
-**Dart:**
-- `lib/optimizely_flutter_sdk.dart` - Public API entry point
-- `lib/src/optimizely_client_wrapper.dart` - Platform channel bridge
-- `lib/src/user_context/optimizely_user_context.dart` - User context API
-- `lib/src/data_objects/` - 21 response/request models
-
-**Android:**
-- `android/src/.../OptimizelyFlutterSdkPlugin.java` - MethodChannel handler
-- `android/src/.../OptimizelyFlutterClient.java` - Core client wrapper
-- `android/build.gradle` - Dependencies & build config
+- Conversion in `Utils.convertToTypedMap()` (lib/src/utils/utils.dart)
+- Test override: `forceIOSFormat` parameter
 
-**iOS:**
-- `ios/Classes/SwiftOptimizelyFlutterSdkPlugin.swift` - MethodChannel handler
-- `ios/optimizely_flutter_sdk.podspec` - Pod dependencies
+**4. Dual MethodChannel Architecture**
+- `optimizely_flutter_sdk` - Main API operations
+- `optimizely_flutter_sdk_logger` - Native → Dart log forwarding
 
 ## Adding Cross-Platform Features
 
 1. Add data models in `lib/src/data_objects/` if needed
-2. Update `optimizely_client_wrapper.dart` with method channel call
+2. Update `lib/src/optimizely_client_wrapper.dart` with MethodChannel call
 3. **Android**: Add case in `OptimizelyFlutterClient.java`, parse args, call native SDK
 4. **iOS**: Add case in `SwiftOptimizelyFlutterSdkPlugin.swift`, parse args, call native SDK
-5. Handle type conversions (iOS requires metadata)
-6. Add tests
-7. Update public API in `optimizely_flutter_sdk.dart`
+5. Handle type conversions (iOS requires metadata wrapping)
+6. Write tests in `test/`
+7. Update public API in `lib/optimizely_flutter_sdk.dart`
+
+## Version Management
+
+**Three locations must stay synchronized:**
+1. `pubspec.yaml` → `version: X.Y.Z`
+2. `lib/package_info.dart` → `version = 'X.Y.Z'`
+3. `README.md` → Installation example `^X.Y.Z`
+
+## Release Workflow
+
+### With Claude Code (Recommended)
+
+Simply ask Claude to create a release:
+```
+"Create release 3.4.2 with ticket FSSDK-12345"
+"Bump patch version with ticket FSSDK-12345"
+```
+
+Claude will execute the full workflow:
+- ✅ Pre-flight checks (master branch, clean working tree)
+- ✅ Create release branch (prepare-X.Y.Z)
+- ✅ Update all 3 version files (pubspec.yaml, package_info.dart, README.md)
+- ✅ Generate CHANGELOG.md template
+- ✅ Commit and push
+- ✅ Create PR
+
+### Manual Release
 
+```bash
+# 1. Create release branch
+git checkout -b prepare-X.Y.Z
+
+# 2. Update versions (pubspec.yaml, package_info.dart, README.md)
+# 3. Update CHANGELOG.md (add release notes at top)
+
+# 4. Commit with standard format
+git commit -m "chore: prepare for release X.Y.Z
+
+Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
+
+# 5. Push and create PR
+git push -u origin prepare-X.Y.Z
+gh pr create --title "[FSSDK-XXXXX] prepare for release X.Y.Z"
+
+# 6. After merge, create GitHub release
+gh release create vX.Y.Z --title "Release X.Y.Z" --draft --target master
+
+# 7. Publish to pub.dev
+flutter pub publish
+```
+
+### CHANGELOG Format
+```markdown
+## X.Y.Z
+Month Day, Year
+
+### New Features / Enhancements / Bug Fixes
+* Description ([#PR](link))
+```
 
-## Contributing
+## Contributing Guidelines
 
-### Commit Format
-Follow [Angular guidelines](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-guidelines): `feat:`, `fix:`, `docs:`, `refactor:`, `test:`
+### Commit Messages
+Follow [Angular guidelines](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-guidelines):
+- `feat:` - New features
+- `fix:` - Bug fixes
+- `chore:` - Maintenance
+- `docs:` - Documentation
+- `refactor:` - Code restructuring
+- `test:` - Test additions
+
+### Branch Strategy
+- **Never commit directly to `master`**
+- Feature branches: `feature/name`, `prepare-X.Y.Z`, `fix/name`
+- All PRs target `master` branch
 
 ### Requirements
-- **Never commit directly to `master` branch** - Always create a feature branch
-- Tests required for all changes
-- PR to `master` branch
-- All CI checks must pass (unit tests, build validation, integration tests)
+- Tests required for all code changes
+- All CI checks must pass (4 parallel workflows)
 - Apache 2.0 license header on new files
+- Sign CLA (Contributor License Agreement)
 
 ### CI Pipeline
-- `unit_test_coverage` (macOS) - Coverage to Coveralls
-- `build_test_android/ios` - Build validation
-- `integration_android/ios_tests` - External test app triggers
+- `unit_test_coverage` (macOS) - Dart tests + Coveralls upload
+- `build_test_android` (Ubuntu) - Android build validation
+- `build_test_ios` (macOS) - iOS build validation
+- `integration_android_tests` (Ubuntu) - Triggers `optimizely-flutter-testapp` repo
+- `integration_ios_tests` (Ubuntu) - Triggers `optimizely-flutter-testapp` repo
 
 ## Platform Requirements
 
-- Dart: >=2.16.2 <4.0.0, Flutter: >=2.5.0
-- Android: minSdk 21, compileSdk 35
-- iOS: 10.0+, Swift 5.0
+**Flutter/Dart:**
+- Dart: >=2.16.2 <4.0.0
+- Flutter: >=2.5.0
+
+**Android:**
+- minSdk: 21 (Android 5.0)
+- compileSdk: 35 (Android 15)
+- Kotlin: 2.1.0
+- Native SDK: android-sdk 5.1.1
+
+**iOS:**
+- Minimum: iOS 10.0
+- Swift: 5.0
+- Native SDK: OptimizelySwiftSDK 5.2.1
+
+## Key Implementation Files
+
+**Dart Layer:**
+- `lib/optimizely_flutter_sdk.dart` - Public API (initialize, decide, track)
+- `lib/src/optimizely_client_wrapper.dart` - Platform bridge (545 LOC)
+- `lib/src/user_context/optimizely_user_context.dart` - User context operations
+- `lib/src/data_objects/` - 21 response/request models
+
+**Android Layer:**
+- `android/src/.../OptimizelyFlutterSdkPlugin.java` - MethodChannel handler
+- `android/src/.../OptimizelyFlutterClient.java` - Core client wrapper (921 LOC)
+- `android/build.gradle` - Dependencies & SDK versions
+
+**iOS Layer:**
+- `ios/Classes/SwiftOptimizelyFlutterSdkPlugin.swift` - Plugin implementation (786 LOC)
+- `ios/Classes/OptimizelyFlutterLogger.swift` - Logger bridge with task queue
+- `ios/optimizely_flutter_sdk.podspec` - CocoaPods dependencies