iOS: Reduce engine/view controller coupling (#57151)

Eliminates some cases where `FlutterViewController` was relying on `FlutterEngine` internals:
* `[FlutterEngine shell]`
* `[FlutterEngine platformView]`
* `[FlutterEngine iosPlatformView]`

Instead, `FlutterEngine` now exposes:
* `installFirstFrameCallback:`
* `enableSemantics:withFlags:`
* `notifyViewCreated`
* `notifyViewDestroyed`
* `waitForFirstFrameSync:callback:`

Also fixes a couple cases where we were relying on transitive header includes:
* `FlutterAppController` relied on `FlutterViewController_Internal.h` for `sendDeepLinkToFramework:completionHandler:`

This is a refactoring followup to #57099 that introduces no semantic changes.

[C++, Objective-C, Java style guides]: https://github.com/flutter/engine/blob/main/CONTRIBUTING.md#style

Author: cbracken

shell/platform/darwin/ios/framework/Source/FlutterAppDelegate.mm

@@ -10,6 +10,7 @@
 #import "flutter/shell/platform/darwin/ios/framework/Source/FlutterAppDelegate_Test.h"
 #import "flutter/shell/platform/darwin/ios/framework/Source/FlutterEngine_Internal.h"
 #import "flutter/shell/platform/darwin/ios/framework/Source/FlutterPluginAppLifeCycleDelegate_internal.h"
+#import "flutter/shell/platform/darwin/ios/framework/Source/FlutterViewController_Internal.h"
 
 FLUTTER_ASSERT_ARC
 

shell/platform/darwin/ios/framework/Source/FlutterEngine.mm

@@ -319,14 +319,48 @@ - (void)dispatchPointerDataPacket:(std::unique_ptr<flutter::PointerDataPacket>)p
   self.platformView->DispatchPointerDataPacket(std::move(packet));
 }
 
-- (fml::WeakPtr<flutter::PlatformView>)platformView {
-  if (!_shell) {
-    return {};
+- (void)installFirstFrameCallback:(void (^)(void))block {
+  if (!self.platformView) {
+    return;
+  }
+
+  __weak FlutterEngine* weakSelf = self;
+  self.platformView->SetNextFrameCallback([weakSelf, block] {
+    FlutterEngine* strongSelf = weakSelf;
+    if (!strongSelf) {
+      return;
+    }
+    FML_DCHECK(strongSelf.platformTaskRunner);
+    FML_DCHECK(strongSelf.rasterTaskRunner);
+    FML_DCHECK(strongSelf.rasterTaskRunner->RunsTasksOnCurrentThread());
+    // Get callback on raster thread and jump back to platform thread.
+    strongSelf.platformTaskRunner->PostTask([block]() { block(); });
+  });
+}
+
+- (void)enableSemantics:(BOOL)enabled withFlags:(int64_t)flags {
+  if (!self.platformView) {
+    return;
+  }
+  self.platformView->SetSemanticsEnabled(enabled);
+  self.platformView->SetAccessibilityFeatures(flags);
+}
+
+- (void)notifyViewCreated {
+  if (!self.platformView) {
+    return;
   }
-  return _shell->GetPlatformView();
+  self.platformView->NotifyCreated();
 }
 
-- (flutter::PlatformViewIOS*)iosPlatformView {
+- (void)notifyViewDestroyed {
+  if (!self.platformView) {
+    return;
+  }
+  self.platformView->NotifyDestroyed();
+}
+
+- (flutter::PlatformViewIOS*)platformView {
   if (!_shell) {
     return nullptr;
   }
@@ -402,16 +436,16 @@ - (void)sendKeyEvent:(const FlutterKeyEvent&)event
 }
 
 - (void)ensureSemanticsEnabled {
-  if (!self.iosPlatformView) {
+  if (!self.platformView) {
     return;
   }
-  self.iosPlatformView->SetSemanticsEnabled(true);
+  self.platformView->SetSemanticsEnabled(true);
 }
 
 - (void)setViewController:(FlutterViewController*)viewController {
-  FML_DCHECK(self.iosPlatformView);
+  FML_DCHECK(self.platformView);
   _viewController = viewController;
-  self.iosPlatformView->SetOwnerViewController(_viewController);
+  self.platformView->SetOwnerViewController(_viewController);
   [self maybeSetupPlatformViewChannels];
   [self updateDisplays];
   self.textInputPlugin.viewController = viewController;
@@ -432,8 +466,8 @@ - (void)setViewController:(FlutterViewController*)viewController {
 }
 
 - (void)attachView {
-  FML_DCHECK(self.iosPlatformView);
-  self.iosPlatformView->attachView();
+  FML_DCHECK(self.platformView);
+  self.platformView->attachView();
 }
 
 - (void)setFlutterViewControllerWillDeallocObserver:(id<NSObject>)observer {
@@ -451,11 +485,8 @@ - (void)notifyViewControllerDeallocated {
   self.textInputPlugin.viewController = nil;
   if (!self.allowHeadlessExecution) {
     [self destroyContext];
-  } else if (_shell) {
-    flutter::PlatformViewIOS* platform_view = [self iosPlatformView];
-    if (platform_view) {
-      platform_view->SetOwnerViewController({});
-    }
+  } else if (self.platformView) {
+    self.platformView->SetOwnerViewController({});
   }
   [self.textInputPlugin resetViewResponder];
   _viewController = nil;
@@ -1215,8 +1246,8 @@ - (FlutterBinaryMessengerConnection)setMessageHandlerOnChannel:(NSString*)channe
                      taskQueue:(NSObject<FlutterTaskQueue>* _Nullable)taskQueue {
   NSParameterAssert(channel);
   if (_shell && _shell->IsSetup()) {
-    self.iosPlatformView->GetPlatformMessageHandlerIos()->SetMessageHandler(channel.UTF8String,
-                                                                            handler, taskQueue);
+    self.platformView->GetPlatformMessageHandlerIos()->SetMessageHandler(channel.UTF8String,
+                                                                         handler, taskQueue);
     return _connections->AquireConnection(channel.UTF8String);
   } else {
     NSAssert(!handler, @"Setting a message handler before the FlutterEngine has been run.");
@@ -1229,18 +1260,18 @@ - (void)cleanUpConnection:(FlutterBinaryMessengerConnection)connection {
   if (_shell && _shell->IsSetup()) {
     std::string channel = _connections->CleanupConnection(connection);
     if (!channel.empty()) {
-      self.iosPlatformView->GetPlatformMessageHandlerIos()->SetMessageHandler(channel.c_str(), nil,
-                                                                              nil);
+      self.platformView->GetPlatformMessageHandlerIos()->SetMessageHandler(channel.c_str(), nil,
+                                                                           nil);
     }
   }
 }
 
 #pragma mark - FlutterTextureRegistry
 
 - (int64_t)registerTexture:(NSObject<FlutterTexture>*)texture {
-  FML_DCHECK(self.iosPlatformView);
+  FML_DCHECK(self.platformView);
   int64_t textureId = self.nextTextureId++;
-  self.iosPlatformView->RegisterExternalTexture(textureId, texture);
+  self.platformView->RegisterExternalTexture(textureId, texture);
   return textureId;
 }
 
@@ -1350,6 +1381,13 @@ - (void)onLocaleUpdated:(NSNotification*)notification {
   [self.localizationChannel invokeMethod:@"setLocale" arguments:localeData];
 }
 
+- (void)waitForFirstFrameSync:(NSTimeInterval)timeout
+                     callback:(NS_NOESCAPE void (^_Nonnull)(BOOL didTimeout))callback {
+  fml::TimeDelta waitTime = fml::TimeDelta::FromMilliseconds(timeout * 1000);
+  fml::Status status = self.shell.WaitForFirstFrame(waitTime);
+  callback(status.code() == fml::StatusCode::kDeadlineExceeded);
+}
+
 - (void)waitForFirstFrame:(NSTimeInterval)timeout
                  callback:(void (^_Nonnull)(BOOL didTimeout))callback {
   dispatch_queue_t queue = dispatch_get_global_queue(QOS_CLASS_BACKGROUND, 0);
@@ -1364,8 +1402,8 @@ - (void)waitForFirstFrame:(NSTimeInterval)timeout
     }
 
     fml::TimeDelta waitTime = fml::TimeDelta::FromMilliseconds(timeout * 1000);
-    didTimeout =
-        strongSelf.shell.WaitForFirstFrame(waitTime).code() == fml::StatusCode::kDeadlineExceeded;
+    fml::Status status = strongSelf.shell.WaitForFirstFrame(waitTime);
+    didTimeout = status.code() == fml::StatusCode::kDeadlineExceeded;
   });
 
   // Only execute the main queue task once the background task has completely finished executing.

shell/platform/darwin/ios/framework/Source/FlutterEnginePlatformViewTest.mm

@@ -11,6 +11,7 @@
 #include "flutter/fml/message_loop.h"
 #import "flutter/shell/platform/darwin/common/framework/Headers/FlutterMacros.h"
 #import "flutter/shell/platform/darwin/ios/framework/Source/FlutterEngine_Internal.h"
+#import "flutter/shell/platform/darwin/ios/framework/Source/FlutterEngine_Test.h"
 #import "flutter/shell/platform/darwin/ios/platform_view_ios.h"
 
 FLUTTER_ASSERT_ARC
@@ -101,7 +102,7 @@ - (void)testCallsNotifyLowMemory {
   XCTAssertNotNil(engine);
   id mockEngine = OCMPartialMock(engine);
   OCMStub([mockEngine notifyLowMemory]);
-  OCMStub([mockEngine iosPlatformView]).andReturn(platform_view.get());
+  OCMStub([mockEngine platformView]).andReturn(platform_view.get());
 
   [engine setViewController:nil];
   OCMVerify([mockEngine notifyLowMemory]);

shell/platform/darwin/ios/framework/Source/FlutterEngineTest.mm

@@ -75,8 +75,6 @@ - (void)testShellGetters {
   XCTAssertNotNil(engine);
 
   // Ensure getters don't deref _shell when it's null, and instead return nullptr.
-  XCTAssertEqual(engine.platformView.get(), nullptr);
-  XCTAssertEqual(engine.iosPlatformView, nullptr);
   XCTAssertEqual(engine.platformTaskRunner.get(), nullptr);
   XCTAssertEqual(engine.uiTaskRunner.get(), nullptr);
   XCTAssertEqual(engine.rasterTaskRunner.get(), nullptr);
@@ -435,10 +433,10 @@ - (void)testSpawnsShareGpuContext {
                                         initialRoute:nil
                                       entrypointArgs:nil];
   XCTAssertNotNil(spawn);
-  XCTAssertTrue([engine iosPlatformView] != nullptr);
-  XCTAssertTrue([spawn iosPlatformView] != nullptr);
-  std::shared_ptr<flutter::IOSContext> engine_context = [engine iosPlatformView]->GetIosContext();
-  std::shared_ptr<flutter::IOSContext> spawn_context = [spawn iosPlatformView]->GetIosContext();
+  XCTAssertTrue(engine.platformView != nullptr);
+  XCTAssertTrue(spawn.platformView != nullptr);
+  std::shared_ptr<flutter::IOSContext> engine_context = engine.platformView->GetIosContext();
+  std::shared_ptr<flutter::IOSContext> spawn_context = spawn.platformView->GetIosContext();
   XCTAssertEqual(engine_context, spawn_context);
 }
 

shell/platform/darwin/ios/framework/Source/FlutterEngine_Internal.h

@@ -25,22 +25,23 @@
 #import "flutter/shell/platform/darwin/ios/framework/Source/FlutterRestorationPlugin.h"
 #import "flutter/shell/platform/darwin/ios/framework/Source/FlutterTextInputDelegate.h"
 #import "flutter/shell/platform/darwin/ios/framework/Source/FlutterTextInputPlugin.h"
-#import "flutter/shell/platform/darwin/ios/platform_view_ios.h"
+#import "flutter/shell/platform/darwin/ios/framework/Source/FlutterView.h"
 
 NS_ASSUME_NONNULL_BEGIN
 
 @interface FlutterEngine () <FlutterViewEngineDelegate>
 
-- (flutter::Shell&)shell;
-
 - (void)updateViewportMetrics:(flutter::ViewportMetrics)viewportMetrics;
 - (void)dispatchPointerDataPacket:(std::unique_ptr<flutter::PointerDataPacket>)packet;
 
 - (fml::RefPtr<fml::TaskRunner>)platformTaskRunner;
 - (fml::RefPtr<fml::TaskRunner>)uiTaskRunner;
 - (fml::RefPtr<fml::TaskRunner>)rasterTaskRunner;
 
-- (fml::WeakPtr<flutter::PlatformView>)platformView;
+- (void)installFirstFrameCallback:(void (^)(void))block;
+- (void)enableSemantics:(BOOL)enabled withFlags:(int64_t)flags;
+- (void)notifyViewCreated;
+- (void)notifyViewDestroyed;
 
 - (flutter::Rasterizer::Screenshot)screenshot:(flutter::Rasterizer::ScreenshotType)type
                                  base64Encode:(bool)base64Encode;
@@ -56,8 +57,13 @@ NS_ASSUME_NONNULL_BEGIN
        initialRoute:(nullable NSString*)initialRoute;
 - (void)attachView;
 - (void)notifyLowMemory;
-- (flutter::PlatformViewIOS*)iosPlatformView;
 
+/// Blocks until the first frame is presented or the timeout is exceeded, then invokes callback.
+- (void)waitForFirstFrameSync:(NSTimeInterval)timeout
+                     callback:(NS_NOESCAPE void (^)(BOOL didTimeout))callback;
+
+/// Asynchronously waits until the first frame is presented or the timeout is exceeded, then invokes
+/// callback.
 - (void)waitForFirstFrame:(NSTimeInterval)timeout callback:(void (^)(BOOL didTimeout))callback;
 
 /**

shell/platform/darwin/ios/framework/Source/FlutterEngine_Test.h

@@ -8,6 +8,7 @@
 #import "flutter/shell/common/shell.h"
 #import "flutter/shell/platform/darwin/ios/framework/Headers/FlutterEngine.h"
 #import "flutter/shell/platform/darwin/ios/framework/Source/FlutterTextInputDelegate.h"
+#include "flutter/shell/platform/darwin/ios/platform_view_ios.h"
 #import "flutter/shell/platform/darwin/ios/rendering_api_selection.h"
 #include "flutter/shell/platform/embedder/embedder.h"
 
@@ -24,6 +25,8 @@ class ThreadHost;
 @property(readonly, nonatomic) BOOL enableEmbedderAPI;
 
 - (flutter::Shell&)shell;
+- (flutter::PlatformViewIOS*)platformView;
+
 - (void)setBinaryMessenger:(FlutterBinaryMessengerRelay*)binaryMessenger;
 - (flutter::IOSRenderingAPI)platformViewsRenderingAPI;
 - (void)waitForFirstFrame:(NSTimeInterval)timeout callback:(void (^)(BOOL didTimeout))callback;

shell/platform/darwin/ios/framework/Source/FlutterPlatformViewsTest.mm

@@ -16,7 +16,7 @@
 #include "flutter/fml/thread.h"
 #import "flutter/shell/platform/darwin/common/framework/Headers/FlutterMacros.h"
 #import "flutter/shell/platform/darwin/ios/framework/Headers/FlutterViewController.h"
-#import "flutter/shell/platform/darwin/ios/framework/Source/FlutterEngine_Internal.h"
+#import "flutter/shell/platform/darwin/ios/framework/Source/FlutterEngine_Test.h"
 #import "flutter/shell/platform/darwin/ios/framework/Source/FlutterPlatformViewsController.h"
 #import "flutter/shell/platform/darwin/ios/framework/Source/FlutterPlatformViews_Internal.h"
 #import "flutter/shell/platform/darwin/ios/framework/Source/FlutterTouchInterceptingView_Test.h"
@@ -4319,8 +4319,8 @@ - (void)testLayerPool {
   // Create an IOSContext and GrDirectContext.
   FlutterEngine* engine = [[FlutterEngine alloc] initWithName:@"foobar"];
   [engine run];
-  XCTAssertTrue([engine iosPlatformView] != nullptr);
-  auto ios_context = [engine iosPlatformView]->GetIosContext();
+  XCTAssertTrue(engine.platformView != nullptr);
+  auto ios_context = engine.platformView->GetIosContext();
   auto gr_context = ios_context->GetMainContext();
 
   auto pool = flutter::OverlayLayerPool{};