fix(cua-driver): state the macOS drag delivery contract in its schema

[hqhq1025]

Summary

drag advertises delivery_mode with a "background" default, and the shared blurb describes that default as "inject without fronting or raising the target — no focus steal". On macOS, window-scope drag refuses "background" unconditionally (platform-macos/src/tools/drag.rs:169-176), so a caller invoking the tool with its documented defaults fails 100% of the time with background_unavailable. Neither the tool description, the delivery_mode blurb, nor mcp-tools.mdx says so — the precondition is only discoverable by hitting the error.

What I checked before writing anything

I looked for an implementation gap first and did not find one, so this PR does not change behavior.

• input/mouse.rs:475 drag_at_xy is a complete background press-drag-release built on post_mouse_event (mouse.rs:901) — the same helper backing background click, right_click, double_click, and scroll, with the same window-local stamp, pid filter and window routing. Its own doc comment says it "uses the SkyLight path for backgrounded-target delivery".
• 768f0650d scoped the refusal to web content ("Background drag is unavailable for web-content windows on macOS", gated on is_electron || is_wk_web_view_app). That commit is not on main.
• 1d0ff7cc3 (fix(cua-driver): macOS e2e convergence (conv2 3/7) #2183) replaced the same pre-image with the unconditional form now on main. The matrix expectations that appear to justify it — cross_platform_behavior_test.rs:1196 and harness_appkit_test.rs:711 — were added in that same commit, so they record the decision rather than an independent observation.

Whatever the reason for the current refusal, a schema whose documented default always fails is a defect on its own. That is all this PR fixes.

Change

• Tool description states the window-scope contract: delivery_mode:"foreground" plus window_id, that the "background" default is refused with background_unavailable, and that scope:"desktop" is exempt.
• delivery_mode moves from the shared delivery_mode_schema() blurb to a drag-specific one via delivery_mode_schema_with. The background/foreground enum is unchanged, so protocol_schema_test's delivery-mode contract still holds.
• The refusal message names window scope and the window_id the foreground rung needs.
• mcp-tools.mdx regenerated from the docs generator; the diff is confined to the drag section.

The runtime default stays "background". DeliveryMode::parse is shared, and defaulting macOS drag to foreground would front a window on an omitted argument — the opposite of the no-foreground contract. Documenting the refusal is the right fix here, not flipping the default.

One thing I left alone

delivery_mode:"foreground" without window_id still falls through to the pid-routed background primitive (drag.rs:316: fg = delivery_mode.is_foreground() && window_id.is_some()), so the driver does perform a background drag on that path while refusing every other caller. I did not touch it — it is a behavior change on a path I cannot exercise from here — but it is worth your eyes, since it suggests the blanket claim is broader than what macOS actually forbids.

There is also a plausible reason the one macOS row that demonstrates the refusal may be measuring the fixture rather than the platform: NSView.acceptsFirstMouse defaults to false, and the AppKit fixture overrides it to true only on ClickTargetButton, not on the NSSlider the background-drag row targets.

Validation

cargo test -p platform-macos --locked                      203 passed, 0 failed
                                                           (200 on main; 3 new schema tests)
cargo test -p cua-driver --test protocol_schema_test        2 passed, 0 failed
cargo fmt --all -- --check                                  clean
git diff --check                                            clean

cargo clippy is unavailable on this toolchain ('cargo-clippy' is not installed for '1.97.1-aarch64-apple-darwin'), so I did not run it. Behavior is unchanged, so the existing slider_drag_px_background refusal row is unaffected; I did not re-run the live macOS harness.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.