This refactoring cleans up VSyncClient's API, separating it into a clean, pure Objective-C API in FlutterVSyncClient.h, and a category that declares an initialiser with C++ types such as fml::TaskRunner and the C++ callback to be fired on vsync boundaries. To avoid hardcoding/redeclaring the Testing category that exposes displayLink and onDisplayLink: I've factored out a FlutterVSyncTesting+Testing.h which can be used in FlutterVSyncClientTest.mm and
FlutterViewControllerTest.mm.

This also renames VSyncClient and DisplayLinkManager to include the "Flutter" prefix, though the Swift names drop the prefix as we do with other classes.

While initialisation of VSyncClient still requires C++ types, this refactoring allows users of VSyncClient such as FlutterKeyboardInsetManager and others to be implemented in Swift. Since this is used throughout the embedder, there's significant value in cleaning up the API, as it unblocks new code from needing to be written in Objective-C++.

This is part of a series of refactorings that aim to place a thin, lightweight layer of abstraction between the core C++ engine and the iOS embedder. Core to this effort are VSyncWaiterIOS, PlatformViewIOS, and IOSExternalViewEmbedder.

Background:

flutter::VsyncWaiter is the core engine's common abstraction for a mechanism for waiting for and getting callbacks on frame boundaries vsync events. These callbacks are used by flutter::Animator to produce frames, but also for other purposes, including frame rate correction for touch events in FlutterViewController and syncing keyboard animations in FlutterKeyboardInsetManager.

flutter::VsyncWaiterIOS is its iOS-specific concrete implementation. VsyncWaiterIOS allocates and owns an Objective-C VSyncClient object which is the core of the waiting mechanism. VSyncClient uses a CADisplayLink under the hood, via a probably extraneous DisplayLinkManager wrapper class.

The general flow looks like:

• On intialisation, VsyncWaiterIOS allocates and initialises a VSyncClient. It hands it a callback that should be called on vsync events, and a task runner whose run loop is used for setting up the CADisplayLink with the correct thread affinity (e.g. the UI thread when used to produce Flutter frames, and to manage insets during keyboard animations, or the platform thread for touch event rate correction).
• core engine calls VsyncWaiter::AwaitVSync() to wait for the next frame boundary. VSyncWaiterIOS calls [VSyncClient await] which unpauses CADisplayLink so it starts sending vsync events.
• On the next vsync from CADisplayLink [VSyncClient onDisplayLink:] is called which calculates high-precision frame_start_time and frame_target_time, pauses CADisplayLink again, then fires the vsync callback, notifying the core engine

Follow-ups:

After this refactoring, I have a follow-up patch that migrates this off the C++ fml::TaskRunner and flutter::TaskRunners types and onto the pure Objective-C FlutterFMLTaskRunner and FlutterFMLTaskRunners classes.

Issue: #112232

Pre-launch Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the AI contribution guidelines and understand my responsibilities, or I am not using AI tools.
• I read the Tree Hygiene wiki page, which explains my responsibilities.
• I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
• I signed the CLA.
• I listed at least one issue that this PR fixes in the description above.
• These patches are Taylored to make migration to Swift a breeze.
• I updated/added relevant documentation (doc comments with ///).
• I added new tests to check the change I am making, or this PR is test-exempt.
• I followed the breaking change policy and added Data Driven Fixes where supported.
• All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.