docs(linux): clarify toolkit-specific windowing contracts - #194921

Description

GTK4 integration exposed GTK3-specific assumptions in the experimental Linux windowing interfaces. This PR documents were some GTK3 toolkit specific API's are used that would need to be solved if GTK4 were to be implemented.

The comments clarify:

• Native registration requires a GTK3 GtkWindow; supporting hosts such as GTK4 GtkPopover requires changes to the registrar and its consumers.
• Interactive move/resize needs toolkit-specific input context; root coordinates and a timestamp are insufficient for GTK4.
• App-paintable behavior is distinct from portable transparency or decoration requests.
• GTK3 and GTK4 GdkRGBA structures have different binary layouts.
• Exported internal FFI signatures must match their framework bindings; adding parameters changes the calling contract.

This is a comments-only preparation PR. It changes no runtime behavior, signatures, layouts, or dependencies and does not introduce GTK4 support. API redesign and implementation remain separate follow-ups.

Related: #94804, #30701, and #193405.

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.
• I updated/added relevant in-code documentation (doc comments with ///).
• 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).
• 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.