Skip to content

[web] Capture pointers to the Flutter view so drags survive platform view iframes - #195187

Merged
auto-submit[bot] merged 7 commits into
flutter:masterfrom
harryterkelsen:capture-pointers-to-the-flutter-view-so-drags
Oct 27, 2026
Merged

auto-submit[bot] merged 7 commits into
flutter:masterfrom
harryterkelsen:capture-pointers-to-the-flutter-view-so-drags

Conversation

@harryterkelsen

Copy link
Copy Markdown
Contributor

On Flutter Web, a drag that starts on Flutter content stops receiving pointermove events when the pointer moves over an <iframe> platform view, because the browser routes those events to the iframe document instead of the host window. As a result, the dragged widget freezes over the iframe and jumps when the pointer re-enters Flutter content.

This PR captures the pointer to the <flutter-view> root on pointerdown when the press targets Flutter content (_viewTarget or flt-glass-pane, to which events inside the scene's shadow root are retargeted), and cancels still-pressed pointers if capture on the view root is involuntarily lost (lostpointercapture). Presses on platform views, the text-editing host, and the semantics host are excluded so native HTML interactions, text selection, and ClickDebouncer accessibility clicks continue to work on their original targets.

This change ships separately from automatic pointer interceptors so that pointer-routing changes for all Flutter web apps can be reviewed and reverted independently.

Review hot spots

  • Boundary events during a captured drag: pointerover/out/enter/leave on other elements (including pointerleave on the view root when dragging outside the window) are suppressed until release.
  • Involuntary capture loss (lostpointercapture): cancels active presses if capture on _viewTarget is lost before pointerup/pointercancel (e.g. window blur or releasePointerCapture), while ignoring lostpointercapture after normal release or bubbling from platform view descendants.
  • Clicks and semantics: after a captured press, click lands on the view root. semanticsHost is excluded from capture so ClickDebouncer and assistive-technology flt-tappable activation remain unchanged (drags starting on semantics nodes remain uncaptured over iframes).
  • Touch, pen, and multi-view: touch already has implicit capture (moving it to the view root is benign), pen drags gain capture alongside mouse drags, and each view captures to its own root.

Fixes #141307

Related: #157968, #134652

Pre-launch Checklist

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.

@github-actions github-actions Bot added engine flutter/engine related. See also e: labels. platform-web Web applications specifically team-web Owned by Web platform team labels Oct 23, 2026
@harryterkelsen harryterkelsen added the CICD Run CI/CD label Oct 23, 2026
@harryterkelsen
harryterkelsen marked this pull request as ready for review October 23, 2026 22:23

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces pointer capture for Flutter content on the web to ensure that drag events remain consistent when crossing iframe boundaries. It adds a _capturePointerIfFlutterContent method to _PointerAdapter to handle pointer capture on the view root, and implements a lostpointercapture event listener to cancel active presses if capture is lost unexpectedly. Corresponding tests have been added to pointer_binding_test.dart to verify capture behavior, error handling, and cancellation logic. I have no feedback to provide as there were no review comments.

mdebbar
mdebbar previously approved these changes Oct 26, 2026
@harryterkelsen harryterkelsen added the autosubmit Merge PR when tree becomes green via auto submit App label Oct 27, 2026
@auto-submit
auto-submit Bot added this pull request to the merge queue Oct 27, 2026
Merged via the queue into flutter:master with commit e06d70d Oct 27, 2026
23 checks passed
@flutter-dashboard flutter-dashboard Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Oct 27, 2026
auto-submit Bot pushed a commit to flutter/packages that referenced this pull request Oct 28, 2026
flutter/flutter@d4c8577...0c2473c

2026-10-28 [email protected] Roll Packages from a8549ae to 13d38e0 (9 revisions) (flutter/flutter#195488)
2026-10-28 [email protected] Use int.oneBitCount in PersistentHashMap and scope 53-bit caps to JS (flutter/flutter#195005)
2026-10-28 [email protected] Roll pub packages (flutter/flutter#195483)
2026-10-28 [email protected] [iPhone Duo] Use the correct UIScreen to report the display size and update when fold/unfold (flutter/flutter#195199)
2026-10-28 [email protected] [fuchsia] Fix portable_ui_test.h includes for newer Fuchsia SDKs (flutter/flutter#195420)
2026-10-28 [email protected] Change default pipeline options to match production draw calls (flutter/flutter#194597)
2026-10-28 [email protected] Roll Fuchsia Test Scripts from 2T18KC7-LDQtmQiLP... to xl1LWBuppzu-BnOzV... (flutter/flutter#195450)
2026-10-27 [email protected] [flutter_tools] Inject dependencies into Darwin build targets, native assets, and Xcode build settings (flutter/flutter#194052)
2026-10-27 [email protected] Revert: Reland square corners fix (flutter/flutter#195436)
2026-10-27 [email protected] [flutter_tools] Add DeviceService app launch and flutter run support for tool extensions (flutter/flutter#194589)
2026-10-27 [email protected] [engine] Honor targetWidth/targetHeight for animated images (flutter/flutter#194615)
2026-10-27 [email protected] [Android][a11y] Set visibleToUser=false for hidden semantics nodes (flutter/flutter#194411)
2026-10-27 [email protected] Fix repo deletion test flake (flutter/flutter#195349)
2026-10-27 [email protected] Roll Packages from 23a05b6 to a8549ae (10 revisions) (flutter/flutter#195434)
2026-10-27 [email protected] [web] Capture pointers to the Flutter view so drags survive platform view iframes (flutter/flutter#195187)
2026-10-27 [email protected] [web] Add opt-in raw samples, measured sample count and warm-up phase hook to the web benchmark recorder (flutter/flutter#195118)
2026-10-27 [email protected] Link migration guide in deprecation messages (flutter/flutter#195361)
2026-10-27 [email protected] Pin basic_material_app_macos__compile to macOS 26 (flutter/flutter#195429)
2026-10-27 [email protected] Add benchmark for warmed pipeline usage (flutter/flutter#195001)
2026-10-27 [email protected] [flutter_tools] Add device log streaming support to DeviceService and ExtensionBackedDevice (flutter/flutter#194964)
2026-10-27 [email protected] Roll Dart SDK from 1d16c04dc346 to 65fc979759ca (4 revisions) (flutter/flutter#195383)

If this roll has caused a breakage, revert this CL and set the roller
to dry run mode using the controls here:
https://autoroll.skia.org/r/flutter-packages
Please CC [email protected],[email protected] on the revert to ensure that a human
is aware of the problem.

To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose

To report a problem with the AutoRoller itself, please file a bug:
https://issues.skia.org/issues/new?component=1389291&template=1850622

Documentation for the AutoRoller is here:
https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
suryaKommana2662 pushed a commit to suryaKommana2662/flutter that referenced this pull request Oct 29, 2026
…view iframes (flutter#195187)

<!--
Thanks for filing a pull request!
Reviewers are typically assigned within a week of filing a request.
To learn more about code review, see our documentation on Tree Hygiene:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
-->

On Flutter Web, a drag that starts on Flutter content stops receiving
`pointermove` events when the pointer moves over an `<iframe>` platform
view, because the browser routes those events to the iframe document
instead of the host window. As a result, the dragged widget freezes over
the iframe and jumps when the pointer re-enters Flutter content.

This PR captures the pointer to the `<flutter-view>` root on
`pointerdown` when the press targets Flutter content (`_viewTarget` or
`flt-glass-pane`, to which events inside the scene's shadow root are
retargeted), and cancels still-pressed pointers if capture on the view
root is involuntarily lost (`lostpointercapture`). Presses on platform
views, the text-editing host, and the semantics host are excluded so
native HTML interactions, text selection, and `ClickDebouncer`
accessibility clicks continue to work on their original targets.

This change ships separately from automatic pointer interceptors so that
pointer-routing changes for all Flutter web apps can be reviewed and
reverted independently.

**Review hot spots**

- **Boundary events during a captured drag:**
`pointerover`/`out`/`enter`/`leave` on other elements (including
`pointerleave` on the view root when dragging outside the window) are
suppressed until release.
- **Involuntary capture loss (`lostpointercapture`):** cancels active
presses if capture on `_viewTarget` is lost before
`pointerup`/`pointercancel` (e.g. window blur or
`releasePointerCapture`), while ignoring `lostpointercapture` after
normal release or bubbling from platform view descendants.
- **Clicks and semantics:** after a captured press, `click` lands on the
view root. `semanticsHost` is excluded from capture so `ClickDebouncer`
and assistive-technology `flt-tappable` activation remain unchanged
(drags starting on semantics nodes remain uncaptured over iframes).
- **Touch, pen, and multi-view:** touch already has implicit capture
(moving it to the view root is benign), pen drags gain capture alongside
mouse drags, and each view captures to its own root.

Fixes flutter#141307

Related: flutter#157968,
flutter#134652

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [AI contribution guidelines] and understand my
responsibilities, or I am not using AI tools.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant in-code documentation (doc comments with
`///`).
- [x] If this PR introduces a new feature or capability, I created and
linked a website documentation issue or PR in [flutter/website] (or
verified none is needed).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [x] 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](https://developers.google.com/gemini-code-assist/docs/review-github-code).
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.

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[AI contribution guidelines]:
https://github.com/flutter/flutter/blob/main/CONTRIBUTING.ai.md
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[flutter/website]: https://github.com/flutter/website
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CICD Run CI/CD engine flutter/engine related. See also e: labels. platform-web Web applications specifically team-web Owned by Web platform team

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[web] Consider using setPointerCapture method for pointer handling.

2 participants