Implements engine-side declarative pointer event handling for semantics. (flutter#176974)

Implements engine-side declarative pointer event handling for semantics.

Framework-side to be implemented in next PR.

Fixes flutter#149001.

**Before change**
https://dialog-dismiss-before.web.app/

Click on the "Show Dialog" button.
Click anywhere inside the dialog that is not a form field.
Observe the dialog being dismissed. 

**After change**
https://dialog-dimiss-after.web.app/

Click on the "Show Dialog" button.
Click anywhere inside the dialog that is not a form field.
Observe the dialog not dismissed.

Author: flutter-zl

engine/src/flutter/lib/ui/semantics.dart

@@ -1156,6 +1156,59 @@ enum Tristate {
   }
 }
 
+/// Describes how a semantic node should behave during hit testing.
+///
+/// This enum allows the framework to communicate pointer event handling
+/// behavior to the platform's accessibility layer. Different platforms
+/// may implement this behavior differently based on their accessibility
+/// infrastructure.
+///
+/// See also:
+///  * [SemanticsUpdateBuilder.updateNode], which accepts this enum.
+enum SemanticsHitTestBehavior {
+  /// Defer to the platform's default hit test behavior inference.
+  ///
+  /// When set to defer, the platform will infer the appropriate behavior
+  /// based on the semantic node's properties such as interactive behaviors,
+  /// route scoping, etc.
+  ///
+  /// On the web, the default inferred behavior is `transparent` for
+  /// non-interactive semantic nodes, allowing pointer events to pass through.
+  ///
+  /// This is the default value and provides backward compatibility.
+  defer,
+
+  /// The semantic element is opaque to hit testing, consuming any pointer
+  /// events within its bounds and preventing them from reaching elements
+  /// behind it in Z-order (siblings and ancestors).
+  ///
+  /// Children of this node can still receive pointer events normally.
+  /// Only elements that are visually behind this node (lower in the stacking
+  /// order) will be blocked from receiving events.
+  ///
+  /// This is typically used for modal surfaces like dialogs, bottom sheets,
+  /// and drawers that should block interaction with content behind them while
+  /// still allowing interaction with their own content.
+  ///
+  /// Platform implementations:
+  ///  * On the web, this results in `pointer-events: all` CSS property.
+  opaque,
+
+  /// The semantic element is transparent to hit testing.
+  ///
+  /// Transparent nodes do not receive hit test events and allow events to pass
+  /// through to elements behind them.
+  ///
+  /// Note: This differs from the framework's `HitTestBehavior.translucent`,
+  /// which receives events while also allowing pass-through. Web's binary
+  /// `pointer-events` property (all or none) cannot support true translucent
+  /// behavior.
+  ///
+  /// Platform implementations:
+  ///  * On the web, this results in `pointer-events: none` CSS property.
+  transparent,
+}
+
 /// Represents a collection of boolean flags that convey semantic information
 /// about a widget's accessibility state and properties.
 ///
@@ -1792,12 +1845,25 @@ abstract class SemanticsUpdateBuilder {
   /// not use this argument should use other ways to communicate validation
   /// errors to the user, such as embedding validation error text in the label.
   ///
+  /// The `hitTestBehavior` describes how this node should behave during hit
+  /// testing. When set to [SemanticsHitTestBehavior.defer] (the default), the
+  /// platform will infer appropriate behavior based on other semantic properties
+  /// of the node itself (not inherited from parent). Different platforms may
+  /// implement this differently.
+  ///
+  /// For example, modal surfaces like dialogs can set this to
+  /// [SemanticsHitTestBehavior.opaque] to block pointer events from reaching
+  /// content behind them, while non-interactive decorative elements can set it
+  /// to [SemanticsHitTestBehavior.transparent] to allow pointer events to pass
+  /// through.
+  ///
   /// See also:
   ///
   ///  * https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/heading_role
   ///  * https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-level
   ///  * [SemanticsValidationResult], that describes possible values for the
   ///    `validationResult` argument.
+  ///  * [SemanticsHitTestBehavior], which describes how hit testing behaves.
   void updateNode({
     required int id,
     required SemanticsFlags flags,
@@ -1835,6 +1901,7 @@ abstract class SemanticsUpdateBuilder {
     SemanticsRole role = SemanticsRole.none,
     required List<String>? controlsNodes,
     SemanticsValidationResult validationResult = SemanticsValidationResult.none,
+    SemanticsHitTestBehavior hitTestBehavior = SemanticsHitTestBehavior.defer,
     required SemanticsInputType inputType,
     required Locale? locale,
   });
@@ -1913,6 +1980,7 @@ base class _NativeSemanticsUpdateBuilder extends NativeFieldWrapperClass1
     SemanticsRole role = SemanticsRole.none,
     required List<String>? controlsNodes,
     SemanticsValidationResult validationResult = SemanticsValidationResult.none,
+    SemanticsHitTestBehavior hitTestBehavior = SemanticsHitTestBehavior.defer,
     required SemanticsInputType inputType,
     required Locale? locale,
   }) {
@@ -1961,6 +2029,7 @@ base class _NativeSemanticsUpdateBuilder extends NativeFieldWrapperClass1
       role.index,
       controlsNodes,
       validationResult.index,
+      hitTestBehavior.index,
       inputType.index,
       locale?.toLanguageTag() ?? '',
     );
@@ -2009,6 +2078,7 @@ base class _NativeSemanticsUpdateBuilder extends NativeFieldWrapperClass1
       Handle,
       Int32,
       Int32,
+      Int32,
       Handle,
     )
   >(symbol: 'SemanticsUpdateBuilder::updateNode')
@@ -2052,6 +2122,7 @@ base class _NativeSemanticsUpdateBuilder extends NativeFieldWrapperClass1
     int role,
     List<String>? controlsNodes,
     int validationResultIndex,
+    int hitTestBehaviorIndex,
     int inputType,
     String locale,
   );

engine/src/flutter/lib/ui/semantics/semantics_update_builder.cc

@@ -70,6 +70,7 @@ void SemanticsUpdateBuilder::updateNode(
     int role,
     const std::vector<std::string>& controlsNodes,
     int validationResult,
+    int hitTestBehavior,
     int inputType,
     std::string locale) {
   FML_CHECK(scrollChildren == 0 ||

engine/src/flutter/lib/ui/semantics/semantics_update_builder.h

@@ -69,6 +69,7 @@ class SemanticsUpdateBuilder
       int role,
       const std::vector<std::string>& controlsNodes,
       int validationResult,
+      int hitTestBehavior,
       int inputType,
       std::string locale);
 

engine/src/flutter/lib/web_ui/lib/semantics.dart

@@ -669,6 +669,8 @@ class LocaleStringAttribute extends StringAttribute {
 
 enum SemanticsValidationResult { none, valid, invalid }
 
+enum SemanticsHitTestBehavior { defer, opaque, transparent }
+
 class SemanticsUpdateBuilder {
   SemanticsUpdateBuilder();
 
@@ -710,6 +712,7 @@ class SemanticsUpdateBuilder {
     SemanticsRole role = SemanticsRole.none,
     required List<String>? controlsNodes,
     SemanticsValidationResult validationResult = SemanticsValidationResult.none,
+    SemanticsHitTestBehavior hitTestBehavior = SemanticsHitTestBehavior.defer,
     required SemanticsInputType inputType,
     required Locale? locale,
   }) {
@@ -754,6 +757,7 @@ class SemanticsUpdateBuilder {
         role: role,
         controlsNodes: controlsNodes,
         validationResult: validationResult,
+        hitTestBehavior: hitTestBehavior,
         inputType: inputType,
         locale: locale,
       ),

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/incrementable.dart

@@ -71,6 +71,14 @@ class SemanticIncrementable extends SemanticRole {
     _focusManager.manage(semanticsObject.id, _element);
   }
 
+  @override
+  bool get acceptsPointerEvents {
+    return switch (semanticsObject.hitTestBehavior) {
+      ui.SemanticsHitTestBehavior.transparent => false,
+      _ => true,
+    };
+  }
+
   @override
   bool focusAsRouteDefault() {
     _element.focusWithoutScroll();

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/semantics.dart

@@ -270,6 +270,7 @@ class SemanticsNodeUpdate {
     required this.role,
     required this.controlsNodes,
     required this.validationResult,
+    this.hitTestBehavior = ui.SemanticsHitTestBehavior.defer,
     required this.inputType,
     required this.locale,
   });
@@ -382,6 +383,9 @@ class SemanticsNodeUpdate {
   /// See [ui.SemanticsUpdateBuilder.updateNode].
   final ui.SemanticsValidationResult validationResult;
 
+  /// See [ui.SemanticsUpdateBuilder.updateNode].
+  final ui.SemanticsHitTestBehavior hitTestBehavior;
+
   /// See [ui.SemanticsUpdateBuilder.updateNode].
   final ui.SemanticsInputType inputType;
 
@@ -581,20 +585,46 @@ abstract class SemanticRole {
   ///
   /// This boolean decides whether to set the `pointer-events` CSS property to
   /// `all` or to `none` on the semantics [element].
+  ///
+  /// The behavior is determined by [ui.SemanticsHitTestBehavior]:
+  /// - `opaque`: Accepts pointer events (blocks elements behind)
+  /// - `transparent`: Rejects pointer events (passes through)
+  /// - `defer`: Infers based on semantic properties (interactive behaviors, etc.)
   bool get acceptsPointerEvents {
+    final hitTestBehavior = semanticsObject.hitTestBehavior;
+
+    switch (hitTestBehavior) {
+      case ui.SemanticsHitTestBehavior.opaque:
+        // Absorb pointer events, blocking them from reaching elements behind.
+        // Used by modal surfaces like dialogs, bottom sheets, drawers.
+        return true;
+      case ui.SemanticsHitTestBehavior.transparent:
+        // Pass through pointer events to elements behind.
+        // Used for non-interactive decorative elements.
+        return false;
+      case ui.SemanticsHitTestBehavior.defer:
+        return _inferAcceptsPointerEvents();
+    }
+  }
+
+  /// Infers whether pointer events should be accepted based on semantic properties.
+  bool _inferAcceptsPointerEvents() {
+    assert(semanticsObject.hitTestBehavior == ui.SemanticsHitTestBehavior.defer);
+
+    // Check if any interactive behavior requires pointer events.
+    // Interactive behaviors (Tappable, SemanticTextField, SemanticIncrementable)
+    // override this to return true, ensuring buttons, text fields, and other
+    // interactive elements receive pointer events when framework defers.
     final behaviors = _behaviors;
     if (behaviors != null) {
       for (final behavior in behaviors) {
-        if (behavior.acceptsPointerEvents) {
+        if (behavior.shouldAcceptPointerEvents) {
           return true;
         }
       }
     }
-    // Ignore pointer events on all container nodes.
-    if (semanticsObject.hasChildren) {
-      return false;
-    }
-    return true;
+
+    return false;
   }
 
   /// Semantic behaviors provided by this role, if any.
@@ -1014,7 +1044,7 @@ abstract class SemanticBehavior {
   ///
   /// This boolean decides whether to set the `pointer-events` CSS property to
   /// `all` or to `none` on [SemanticsObject.element].
-  bool get acceptsPointerEvents => false;
+  bool get shouldAcceptPointerEvents => false;
 
   /// Called immediately after the [semanticsObject] updates some of its fields.
   ///
@@ -1466,6 +1496,17 @@ class SemanticsObject {
     _dirtyFields |= _validationResultIndex;
   }
 
+  /// See [ui.SemanticsUpdateBuilder.updateNode].
+  ui.SemanticsHitTestBehavior get hitTestBehavior => _hitTestBehavior;
+  ui.SemanticsHitTestBehavior _hitTestBehavior = ui.SemanticsHitTestBehavior.defer;
+
+  static const int _hitTestBehaviorIndex = 1 << 28;
+
+  bool get isHitTestBehaviorDirty => _isDirty(_hitTestBehaviorIndex);
+  void _markHitTestBehaviorDirty() {
+    _dirtyFields |= _hitTestBehaviorIndex;
+  }
+
   /// A unique permanent identifier of the semantics node in the tree.
   final int id;
 
@@ -1778,6 +1819,11 @@ class SemanticsObject {
       _markValidationResultDirty();
     }
 
+    if (_hitTestBehavior != update.hitTestBehavior) {
+      _hitTestBehavior = update.hitTestBehavior;
+      _markHitTestBehaviorDirty();
+    }
+
     role = update.role;
 
     inputType = update.inputType;

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/tappable.dart

@@ -51,7 +51,7 @@ class Tappable extends SemanticBehavior {
   }
 
   @override
-  bool get acceptsPointerEvents => true;
+  bool get shouldAcceptPointerEvents => true;
 
   DomEventListener? _clickListener;
   bool _isListening = false;

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/text_field.dart

@@ -208,7 +208,12 @@ class SemanticTextField extends SemanticRole {
   }
 
   @override
-  bool get acceptsPointerEvents => true;
+  bool get acceptsPointerEvents {
+    return switch (semanticsObject.hitTestBehavior) {
+      ui.SemanticsHitTestBehavior.transparent => false,
+      _ => true,
+    };
+  }
 
   /// The element used for editing, e.g. `<input>`, `<textarea>`, which is
   /// different from the host [element].