[predatorx7]

Closes #11

Root cause

On Android the plugin hands evaluateJavaScriptAsync the user's script and forwards whatever string comes back. androidx.javascriptengine only returns the completion value when it is a JS string; every other type (numbers, booleans, objects, undefined) is coerced to "". The Dart side then ran a parseValue heuristic that guessed a type from the string content, so a JS string "42" became int 42 and '{"a":1}' became a Map, while a real JS number 42 arrived as "". A genuine empty string was indistinguishable from a coerced one.

Darwin (JavaScriptCore over FFI) had its own, different problems: NaN, Infinity, 1e21 and 2 ** 63 threw FormatException out of the typed converter; Promise results were JSON-encoded twice (Promise.resolve("hi") returned "\"hi\""); undefined, functions, symbols, bigints and circular objects silently became null; a rejected promise lost its reason ({}); and a plain-string channel message failed to decode.

So the two platforms disagreed with each other and with the README.

The contract (now identical on both platforms)

runJavaScriptReturningResult / runJavaScriptFromFileReturningResult:

1. The value the script evaluates to (its completion value), or the value a returned Promise resolves to, is returned to Dart as a String exactly as-is. No JSON decoding, no number/bool parsing, no type detection. "" is "".
2. If that value is not a JS string, the future resolves to '' on every platform. Callers who want structured data end their script with JSON.stringify(...) and jsonDecode it in Dart. The plugin deliberately does not parse the user's script to recover a typed last expression; scripts can be megabytes and that is the caller's job if they want it.
3. Promises are awaited (Android needs a WebView with JS_FEATURE_PROMISE_RETURN; a warning is logged otherwise). A rejection, a thrown error or a parse failure throws a JavaScriptExecutionException carrying the JS message.
4. Channels: sendMessage(name, string) is delivered verbatim to JavaScriptMessage.message; JavaScriptReply.message reaches JS verbatim; a null reply resolves the JS promise with null; a non-string message or an unregistered channel name throws in JS.
5. The declared return type stays Future<Object?> (the public API does not change); it always resolves to a String and may be narrowed in a future major.

⚠️ Behavior change (deliberate, documented, minor bump)

Android no longer auto-JSON-decodes results. A JS string "42" is now the Dart String '42', not int 42; '{"a":1}' is the JSON text, not a Map. Darwin no longer returns typed numbers/bools/objects. Migration: jsonDecode(result as String) where you relied on auto-decoding; end scripts with JSON.stringify(...) where you relied on typed results. Called out at the top of the javascript_flutter 1.3.0 and javascript_android 2.2.0 changelogs and in the README.

Commits (in order)

1. build: modernize toolchain, CI and the example app (tooling only, no behavior change). Plugin Gradle moved to Kotlin DSL on AGP 9.1 / Kotlin 2.4 / Java 17 / compileSdk 36 matching the Flutter 3.47 plugin template; minSdk declared as 26 (the engine already required it); pigeon 26 → 29 with @asyncCallback so the Kotlin surface is unchanged; example platform folders regenerated with flutter create (Gradle 9.3.1, SwiftPM) keeping lib/; the old Gradle 8.12 wrapper could not run on JDK 25. CI: the eight old workflows had paths: filters without the packages/ prefix (they never triggered) and referenced packages and fluttium flows that do not exist; replaced by one workflow that formats, analyzes and tests every package, builds the example APK, and runs the device integration tests on an Android emulator, an iOS simulator and macOS desktop. Dependabot now points at real directories. Requires Flutter ≥ 3.44 (flutter_tools applies the Kotlin Gradle plugin to plugins automatically from that version); the pubspec constraints say so.
2. fix(darwin): the contract, every Darwin bug above, and the shared device test packages/javascript/example/integration_test/javascript_test.dart that pins the contract and must pass on all three targets. javascript_platform_interface 2.1.0 documents the contract. One small, commented patch to the vendored runtime: isError now comes from a real exception ref rather than result.startsWith('ERROR:'), so a script returning "ERROR: x" is no longer reported as a failure and throw "str" is.
3. fix(android): results returned verbatim; androidx.javascriptengine 1.0.0 → 1.1.1 and channel messaging over a MessagePort (createMessageChannel / android.getNamedPort) when JS_FEATURE_MESSAGE_PORTS is supported, falling back to the console-messaging hack when JS_FEATURE_CONSOLE_MESSAGING is supported, then to timer polling. The fallback transports are kept intact and are exercised on-device by integration_test/android_transports_test.dart, which forces each transport via @visibleForTesting hooks and skips the ones a device lacks. Also fixed while there: start-up failures leaked the isolate/port/polling timer, message ids collided when a channel was re-added, and in-flight sends on a removed channel never settled.
4. docs: README, dartdoc, example (JSON.stringify + jsonDecode pattern), changelogs, 15 unit tests pinning the JavaScript facade API, example widget test, cspell words.

Verification

Check	Result
dart format --set-exit-if-changed, flutter analyze, flutter test in all 4 packages + example	clean; 12 / 15 / 39 / 81 / 5 tests pass
javascript_darwin tests run the real JavaScriptCore on the macOS host	81 pass, pin every contract row by name
integration_test/javascript_test.dart on Android emulator (API 37, WebView 153)	78 pass
integration_test/android_transports_test.dart on the same emulator	21 pass (7 per transport); logcat shows Message port transport ...: enabled by default
integration_test/javascript_test.dart on iPhone 17 Pro simulator	78 pass
integration_test/javascript_test.dart on macOS desktop	78 pass
flutter build apk --debug, flutter build ios --simulator, flutter build macos, flutter run -d emulator of the example	all succeed
cspell over **/*.md	0 issues

Not verified / caveats

• First CI run: every job passed except example-ios, which hung for 6 hours after the Xcode build. A diagnostic run (ci: temporary iOS simulator diagnostics (not for merge) #14, throwaway) showed the app launches but a simulator booted only via simctl never surfaces the "Dart VM Service is listening" log line on the hosted macOS 26 / Xcode 26.6 runner, so flutter test -d waits forever; with Simulator.app opened on the booted device the same job passes all 78 tests. The workflow now opens Simulator.app after boot and every job has a timeout-minutes. Even with that, one run on an overloaded macOS fleet (GitHub annotated the sibling macOS job with "not acquired by Runner of type hosted") hung again while the identical code passed minutes earlier on ci: temporary iOS simulator diagnostics (not for merge) #14, so both Apple test steps run flutter test under a 10-minute watchdog and retry only on a hang (SIGALRM, exit 142); a real test failure still fails immediately. On the final green run the first simulator attempt hung and the retry passed, so expect the iOS job to take ~17 minutes when that happens and ~8 when it does not. The job also quits Simulator.app itself, otherwise the runner's post-job cleanup stalls for minutes.
• The CI emulator (API 36 google_apis) ships a WebView without JS_FEATURE_MESSAGE_PORTS: the transport test skips its 7 message-port cases there (visible as "⏭️ Skipped tests" in the job log) and the contract suite runs over the console-messaging fallback, which is the intended degradation. I tried to get message ports covered in CI with API 37.0 google_apis and 37.1/37.2 google_apis_ps16k x86_64 images; all three time out booting on the hosted runner, so the message-port transport is verified only locally (API 37.1 emulator, WebView 153, 21/21 transport tests, logcat Message port transport ...: enabled).
• The JS_FEATURE_PROMISE_RETURN-unsupported path and the Kotlin createMessageChannel exception fallback are covered by Dart fakes only; every available emulator supports both features.
• Running both integration files in one flutter test integration_test -d macos invocation is flaky in the Flutter tool (second desktop app launch fails with "Error waiting for a debug connection"), so the Apple CI jobs run the contract file only; the transports file is Android-only anyway.
• Pigeon regen and the vendored-file reformat in commit 1 are mechanical.

🤖 Generated with Claude Code