macOS: add traffic‑light inset API and demo example

[AndrewJSchoen]

• Tested on all platforms changed
• Added an entry to the changelog module if knowledge of this change could be valuable to users
• Updated documentation to reflect any user-facing changes, including notes of platform-specific behavior
• Created or updated an example program if it would help users understand this functionality

Description:

• Adds WindowAttributesMacOS::with_traffic_light_inset and WindowExtMacOS::set_traffic_light_inset to offset the traffic‑light buttons in logical points.
• Applies the inset reliably across title changes, resizes, and fullscreen transitions; no effect when titlebar buttons are hidden.
• Adds traffic_lights example for interactive adjustment (arrow keys, Shift for coarse, R reset, Esc exit).
• Adds changelog entry in winit/src/changelog/unreleased.md.

Fixes #4436

Tests:

• cargo check -p winit-appkit
• cargo check -p winit --example traffic_lights

[AndrewJSchoen]

I think this should be ready to go if everything checks out with the owners.

[AndrewJSchoen]

A note on this:

I can reproduce a “dual hover” issue after applying the traffic‑light inset: the original (pre‑inset) hover region still highlights the buttons, even though clicks only work at the new position. I tried some fixes, such as resizing the titlebar container/titlebar view and forcing tracking area refreshes (updateTrackingAreas, invalidateCursorRectsForView, setFrame), but the old hover region persists.

This appears to be tied to AppKit internals: standard traffic‑light hover is driven by a private superview method (_mouseInGroup:) on the titlebar superview (see https://stackoverflow.com/questions/7634788). That implies the hover tracking is not solely based on the button frames and may not be fixable without private API or a full custom titlebar implementation. If anyone has any suggestions on that or knows more, I would be interested in any solutions.

Otherwise, it might be worth documenting this limitation (hover highlight remains at the original location) and/or recommending a custom decorator approach for apps that need inset traffic lights with correct hover behavior (e.g. #4450), which seems to be more similar to the approach Tauri uses.

[nicoburns]

From your StackOverflow link https://stackoverflow.com/a/36292700/140293 and https://stackoverflow.com/a/30417372/140293 both look like they might work to fix the issue you're seeing.