[pigeon] Separate native interop Dart bindings into a conditionally imported companion file - #13393

Since _writeNativeInteropFileImports imports the main generated file without a prefix, naming these top-level extensions ${name}NativeInterop can shadow a user-defined class, enum, or API with that name (which isn't blocked by disallowedPrefixes). For example:

import 'package:pigeon/pigeon.dart';

class Foo {
  Foo({this.x});
  int? x;
}

class FooNativeInterop {
  FooNativeInterop({this.y});
  String? y;
}

@HostApi()
abstract class FooApi {
  FooNativeInterop convert(Foo input, FooNativeInterop existing);
}

Validation passes, and in the companion file extension FooNativeInterop on Foo shadows the imported FooNativeInterop class across the whole file, breaking extension FooNativeInteropNativeInterop on FooNativeInterop, FooNativeInterop(...) in fromJni/fromFfi, and the method signatures on _FooApiForNativeInterop. Since nothing outside the companion file references these extensions by name (except sealed class fromJni/fromFfi in the same file), giving the extensions a private or reserved prefix (or prefixing the main-file import) would avoid any collision.

Before this split, ${api.name}Registrar was the actual instance passed to implement(this) / captured by the Objective-C protocol builder closures, which read dartApi on each callback.

Now ${api.name}Registrar still exposes a public mutable dartApi field and sets dartApi = api; here, while pigeonRegister_${api.name} allocates a separate _${api.name}Registrar() in the companion file with its own dartApi:

1. ${api.name}Registrar.dartApi in the main file is never read anywhere, so mutating registrar.dartApi after registration (for example setting it to null or swapping implementations) silently has no effect on registered native callbacks, and all the if (dartApi != null) ... else branches in _${api.name}Registrar become unreachable.
2. On Web, calling registrar.register(api) mutates registrar.dartApi = api before the stub throws UnsupportedError.

Should ${api.name}Registrar pass itself to pigeonRegister_${api.name} (or drop the public dartApi field if mutating it after registration isn't meant to be supported)?

The dartOut check here (dartOut != null && dartOut!.isNotEmpty && dartOut != 'stdout') doesn't line up with writeFileImports (which only checks dartOut != null) or DartGeneratorAdapter.validate:

• When dartOut is 'stdout' (supported by Pigeon for CLI output, and currently allowed by validate with native interop) or '', this skips writing the companion file while writeFileImports still emits import './stdout' if (dart.library.ffi) './stdout.native_interop.dart' as pigeon_native; for files that don't exist.
• Conversely, if DartGenerator.generate is called with dartOut: null, writeFileImports omits the pigeon_native import while writeFlutterApi and _writeHostApiNativeInteropInterface still emit pigeon_native.* calls.

Should DartGeneratorAdapter.validate reject dartOut == 'stdout' (and empty dartOut) when native interop is enabled, and keep the pigeon_native import/call emission consistent when dartOut is null?

Two small things on pigeonRegister_${api.name} and pigeonGetInstance_${api.name} since conditional imports require them to be public top-level functions:

1. disallowedPrefixes reserves pigeon_ (with the underscore), pigeonVar_, pigeonChannelCodec, and capitalized Pigeon, so lowercase pigeonGetInstance_ and pigeonRegister_ aren't reserved. A schema like:

   import 'package:pigeon/pigeon.dart';
   
   class pigeonGetInstance_PingApi {
     pigeonGetInstance_PingApi({this.id});
     int? id;
   }
   
   @HostApi()
   abstract class PingApi {
     void ping(pigeonGetInstance_PingApi payload);
   }

   passes validation and emits duplicate top-level pigeonGetInstance_PingApi declarations in the main file. Using an existing disallowed prefix (such as pigeon_ or PigeonInternal) avoids that.
2. Since plugins may re-export the main generated file (like in [shared_preferences_android] Fix web compilation of apps that import the package #13380), marking these functions @internal (from package:meta/meta.dart, already imported above) would keep them out of external autocomplete and warn if anyone calls the main-file stubs directly (where they unconditionally throw UnsupportedError even on Android and iOS).