See go/flutter-semantics-abi.

Work

• Introduce CODEOWNERS for the embedder API: [Embedder API] Add CODEOWNERS engine#39784
• Document the new "array of pointers" recommendation to the embedder API [Embedder API] Add 'array of pointers' guidance engine#39804
• Introduce a new update semantics embedder API whose ABI is stable. Deprecate the old semantics API. [Embedder API] Introduce new update semantics callback engine#39807
• Move all embedders to the new semantics API
  • Windows: [Windows] Use the new update semantics embedder API engine#40072
  • macOS: [macOS] Use the new update semantics embedder API engine#40584
  • Tizen:
• Remove common embedder code that is now unused: Complete the update semantics embedder API migration engine#40773

Background

Flutter 3.7 introduced a new embedder API for semantic updates: flutter/engine#37129. The Tizen embedder has migrated to this new API: flutter-tizen/embedder#24.

The embedder API should provide full forward and backward ABI compatibility. However, adding new members to FlutterSemanticsNode or FlutterSemanticsCustomAction may cause external embedders to crash if they update the engine without recompiling.

For example:

FlutterSemanticsUpdate update = ...;
FlutterSemanticsNode first = updates.nodes[0];
FlutterSemanticsNode second = updates.nodes[1]; // BAD! This could crash

The array indexing might crash if the external embedder wasn't recompiled after an engine update. Instead, external embedders must determine the size of FlutterSemanticsNode or FlutterSemanticsCustomAction using their struct_size member. Something like:

FlutterSemanticsUpdate update = ...;
FlutterSemanticsNode first = updates.nodes[0];
FlutterSemanticsNode second = static_cast<FlutterSemanticsNode*>(
    static_cast<char*>(update.nodes) + 1 * first.struct_size);

This problem would've been avoided if FlutterSemanticsUpdate.nodes or FlutterSemanticsUpdate.custom_actions were arrays of pointers to structs instead of arrays of structs.