Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
fix(cua-driver): repair native Hyprland foreground regressions (#4396)
Francesco Bonacci51003ab368f3
diff --git a/libs/cua-driver/docs/hyprland-edge-input-regressions.md b/libs/cua-driver/docs/hyprland-edge-input-regressions.mdnew file mode 100644index 0000000000..ffe638c3ec--- /dev/null+++ b/libs/cua-driver/docs/hyprland-edge-input-regressions.md@@ -0,0 +1,25 @@+# Native Hyprland regression repair++Driver `0.31.0` at `5272e492d61b96caf08e3bf434d91126c1f3dccc`,+running the unchanged canonical Linux suite on Hyprland `0.56.2-3`, exposes+these focused foreground failures:++- Both Tauri scroll targeting modes request two pages but deliver only 126+ pixels into a 128-pixel viewport. The compositor route discards `by=page`.+- Keyboard-first named-session input leaves its cursor position unset.+- GTK3 supplies window-local accessibility bounds that the Driver incorrectly+ trusts as screen coordinates, producing an out-of-capture pixel target.++This workstream repairs those exact failures and adds focused regression+coverage. It does not change application admission, multi-monitor behavior,+or the keyboard transaction redesign. Refs #3011.+The Edge kit evidence and proof-harness changes remain in #4395 / #4216.++Acceptance requires focused native replays, independent review, ordinary CI,+and the complete canonical native gate at the final candidate. No test+threshold or outside-capture assertion is waived.++At candidate `8f026edc1fefa4428969c36826e34c7d385a0f5e`, on Omarchy Edge with+Hyprland `0.56.2-4`, the complete native suite delivered 90 cases and refused+42 as expected, with none failed or skipped. The manual foreground and native+observation gates also passed. #4396 records the full cross-platform evidence.diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/recording.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/recording.rsindex 6bbf71996d..a3c9eaf04d 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/recording.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/recording.rs@@ -2330,13 +2330,24 @@ mod tests {RecordingCaller::default(),).expect("resolved refusal should reserve an evidence turn");- let refusal_record = crate::action_record::ActionExecutionRecord::builder(- crate::action_record::ActionEffect::Refused,- crate::action_record::ActionTransport::WindowsTargetedInjection,- crate::action_record::RequestedDelivery::Background,+ // Derive the record from the real shared stale-zoom refusal so the+ // recorder is proven to treat it as refused-before-dispatch (no+ // click marker), not as an unverifiable delivered click.+ let zoom_refusal = cache+ .zoom(1, Some(2), None)+ .expect_err("no zoom context was published")+ .structured_content+ .expect("zoom refusal is structured");+ let refusal_record = crate::action_record::ActionExecutionRecord::from_legacy(+ "click",+ &serde_json::json!({"pid": 1, "window_id": 2, "x": 3, "y": 4, "from_zoom": true}),+ &zoom_refusal,)- .build()- .expect("valid refusal record");+ .expect("click refusal normalizes to an action record");+ assert_eq!(+ refusal_record.effect,+ crate::action_record::ActionEffect::Refused+ );session.finish_turn_with_outcome(pending,"refused before dispatch",diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/snapshot_store.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/snapshot_store.rsindex b30a5573d7..e61290c894 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/snapshot_store.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/snapshot_store.rs@@ -108,10 +108,13 @@ fn stale_token_refusal<S>(pid: i32, lane: &[Snapshot<S>]) -> ToolResult {}fn zoom_context_refusal(pid: i32, window_id: Option<u64>) -> ToolResult {- ToolResult::error(- "The zoom coordinate context is missing or was replaced by a newer snapshot. Call get_window_state and zoom again on the same connection before using from_zoom coordinates.",- )- .with_structured(serde_json::json!({+ let message = "The zoom coordinate context is missing or was replaced by a newer snapshot. Call get_window_state and zoom again on the same connection before using from_zoom coordinates.";+ ToolResult::error(message).with_structured(serde_json::json!({+ // Explicit shared refusal envelope: the context is resolved before any+ // input is dispatched, so nothing was delivered. Top-level fields stay+ // for existing consumers.+ "status": "refused",+ "refusal": { "code": "zoom_context_missing", "message": message },"code": "zoom_context_missing","pid": pid,"window_id": window_id,@@ -633,6 +636,34 @@ mod tests {);}+ #[test]+ fn stale_zoom_is_an_explicit_refusal_with_no_delivery() {+ let cache = SnapshotStore::<Payload>::new();+ let structured = cache+ .zoom(7, Some(9), None)+ .unwrap_err()+ .structured_content+ .unwrap();+ // Legacy top-level fields remain for existing consumers.+ assert_eq!(structured["code"], "zoom_context_missing");+ assert_eq!(structured["pid"], 7);+ assert_eq!(structured["window_id"], 9);+ assert_eq!(structured["status"], "refused");+ assert_eq!(structured["refusal"]["code"], "zoom_context_missing");++ let args = serde_json::json!({+ "pid": 7, "window_id": 9, "x": 1, "y": 2, "from_zoom": true,+ "delivery_mode": "foreground",+ });+ let record =+ crate::action_record::ActionExecutionRecord::from_legacy("click", &args, &structured)+ .unwrap();+ assert_eq!(record.effect, crate::action_record::ActionEffect::Refused);+ assert_eq!(record.actual_delivery, None);+ assert_eq!(record.delivered_count, None);+ assert_eq!(record.refusal.unwrap().code, "zoom_context_missing");+ }+#[test]fn clear_then_publish_starts_clean() {let cache = SnapshotStore::new();diff --git a/libs/cua-driver/rust/crates/platform-linux/src/atspi/native.rs b/libs/cua-driver/rust/crates/platform-linux/src/atspi/native.rsindex 982db3c72e..8abb4b69eb 100644--- a/libs/cua-driver/rust/crates/platform-linux/src/atspi/native.rs+++ b/libs/cua-driver/rust/crates/platform-linux/src/atspi/native.rs@@ -3687,6 +3687,7 @@ pub fn element_bounds_ref(let display = (!crate::wayland::is_wayland()).then(x11_display_size).flatten();+ let origin_attested = native_wayland_origin_attested(pid, xid);bounded_for(REF_ACTION_BUDGET,async {@@ -3704,7 +3705,7 @@ pub fn element_bounds_ref(};if coord == CoordType::Window {if let Some(Ok(raw)) = call(component.get_extents(CoordType::Screen)).await {- if screen_extents_trusted(raw, display) {+ if screen_answer_overrides_window(raw, display, origin_attested) {return project_screen_extents(raw, (0, 0), None).ok_or_else(|| anyhow!("cached element reports no on-screen extents"));}@@ -5558,6 +5559,31 @@ pub(crate) fn screen_extents_trusted(}}+/// Whether a `CoordType::Screen` answer may override the Window-relative+/// reconstruction. GTK3 on native Wayland reports window-local values as+/// `Screen` (no display bounds exist to reject them), so a compositor-attested+/// native client's origin plus `Window` extents must win. XWayland clients+/// report true screen extents and are never attested.+fn screen_answer_overrides_window(+ raw: (i32, i32, i32, i32),+ display: Option<(u32, u32)>,+ native_origin_attested: bool,+) -> bool {+ !native_origin_attested && screen_extents_trusted(raw, display)+}++/// True only when the Hyprland compositor identifies this exact client+/// (nonzero address `xid` AND `pid`) as native Wayland, not XWayland. Missing,+/// mismatched, or unreported clients fail closed, so `Screen` extents keep+/// winning, which is correct for XWayland GTK and LibreOffice. Performs+/// blocking compositor IPC: async callers must use `bounded_blocking`.+fn native_wayland_origin_attested(pid: u32, xid: u64) -> bool {+ xid != 0+ && crate::wayland::is_wayland()+ && crate::wayland::hyprland::is_session()+ && crate::wayland::hyprland::native_client_attested(xid, pid)+}+pub(crate) fn x11_window_origin(xid: u64) -> Option<(i32, i32)> {use x11rb::protocol::xproto::*;use x11rb::rust_connection::RustConnection;@@ -6083,6 +6109,9 @@ async fn element_bounds_for_visited(// Bounds are independent read-only queries. Overlap a bounded number of// calls instead of serializing thousands of unrealized menu components.// Preserve original indices, all extents checks, and per-call timeouts.+ let origin_attested = bounded_blocking(move || native_wayland_origin_attested(pid, xid))+ .await+ .unwrap_or(false);let queries = scoped_component_nodes(&action_nodes, scoped_frame, |node| {(node.frame_ordinal, node.has_component)})@@ -6094,7 +6123,7 @@ async fn element_bounds_for_visited(// origin path.if coord == CoordType::Window && !node.in_web_doc {if let Some(Ok(raw)) = call(comp.get_extents(CoordType::Screen)).await {- if screen_extents_trusted(raw, display) {+ if screen_answer_overrides_window(raw, display, origin_attested) {return project_screen_extents(raw, (0, 0), None).map(|bounds| (idx, bounds));}}@@ -6203,6 +6232,85 @@ mod screen_extents_tests {}}+#[cfg(test)]+mod screen_override_tests {+ use super::{project_screen_extents, screen_answer_overrides_window};++ #[test]+ fn attested_origin_rejects_window_local_screen_answer() {+ // GTK3 on Hyprland reports window-local (12,211) as Screen; with no+ // display bounds it would otherwise pass `screen_extents_trusted`.+ let local = (12, 211, 917, 34);+ assert!(screen_answer_overrides_window(local, None, false));+ assert!(!screen_answer_overrides_window(local, None, true));+ // Window extents plus the attested nonzero origin give screen space.+ assert_eq!(+ project_screen_extents(local, (955, 349), None),+ Some((967, 560, 917, 34))+ );+ }++ #[test]+ fn xwayland_or_unattested_screen_answer_wins() {+ // XWayland GTK/LibreOffice report true screen extents; without an+ // exact native-client attestation they must not be discarded. A zero+ // address never attests, without consulting the compositor.+ assert!(!super::native_wayland_origin_attested(1, 0));+ assert!(super::screen_answer_overrides_window(+ (967, 560, 917, 34),+ None,+ super::native_wayland_origin_attested(1, 0)+ ));+ }++ #[test]+ fn native_attested_window_local_screen_answer_loses_to_window_extents() {+ assert!(!super::screen_answer_overrides_window(+ (10, 20, 800, 600),+ None,+ true+ ));+ }++ #[test]+ fn x11_screen_answer_still_wins_with_display_bounds() {+ let screen = (70, 110, 848, 433);+ assert!(screen_answer_overrides_window(+ screen,+ Some((1920, 1080)),+ false+ ));+ }++ #[test]+ fn invalid_screen_answers_never_override() {+ for attested in [false, true] {+ assert!(!screen_answer_overrides_window(+ (i32::MIN, i32::MIN, 1, 1),+ None,+ attested+ ));+ assert!(!screen_answer_overrides_window(+ (0, 0, 100, 20),+ None,+ attested+ ));+ }+ assert_eq!(+ project_screen_extents((i32::MIN, i32::MIN, 1, 1), (955, 349), None),+ None+ );+ }++ #[test]+ fn web_document_origin_is_added_after_window_offset() {+ assert_eq!(+ project_screen_extents((10, 20, 30, 40), (955, 349), Some((0, 80))),+ Some((965, 449, 30, 40))+ );+ }+}+#[cfg(test)]mod stacking_z_index_tests {use super::z_index_from_stacking;diff --git a/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rs b/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rsindex d5d3855a8e..33d7685288 100644--- a/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rs+++ b/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rs@@ -4502,6 +4502,40 @@ async fn foreground_hyprland_action()}+async fn foreground_hyprland_scroll(+ args: &Value,+ pid: u32,+ xid: u64,+ actions: Vec<crate::wayland::hyprland_input::Action>,+) -> ToolResult {+ if !crate::wayland::hyprland_input::enabled() {+ return foreground_hyprland_refusal("production Hyprland input plugin is unavailable");+ }+ let owner = named_session_cursor_key(args);+ let (_cancellation, dispatch) = match spawn_isolated_hyprland(args, move |cancellation| {+ crate::wayland::hyprland_input::execute_foreground_scroll(+ owner,+ pid,+ xid,+ actions,+ cancellation,+ )+ }) {+ Ok(dispatch) => dispatch,+ Err(_) => return foreground_hyprland_refusal("authenticated admitted lifecycle required"),+ };+ hyprland_input_result(+ match dispatch.await {+ Ok(result) => result,+ Err(error) => Err(crate::wayland::hyprland_input::unknown_dispatch(+ error.into(),+ 0,+ )),+ },+ true,+ )+}+fn foreground_hyprland_key(key: String,mut modifiers: Vec<String>,@@ -7293,6 +7327,8 @@ impl Tool for TypeTextTool {Ok(_) => return isolated_hyprland_refusal("background text must not be empty"),Err(error) => return isolated_hyprland_refusal(error.to_string()),}+ position_named_session_keyboard_cursor(&self.state, &args, pid, xid, None, None, true)+ .await;let owner = named_session_cursor_key(&args);let (_cancellation, dispatch) =match spawn_isolated_hyprland(&args, move |cancellation| {@@ -7350,6 +7386,16 @@ impl Tool for TypeTextTool {.await,Ok(Ok(()))) {+ position_named_session_keyboard_cursor(+ &self.state,+ &args,+ pid,+ xid,+ resolved_elem_idx,+ None,+ true,+ )+ .await;return type_text_ax_result(pid,text.chars().count(),@@ -7375,7 +7421,20 @@ impl Tool for TypeTextTool {{return error;}- if named_session_cursor_key(&args).is_none() {+ if named_session_cursor_key(&args).is_some() {+ if px.is_none() {+ position_named_session_keyboard_cursor(+ &self.state,+ &args,+ pid,+ xid,+ resolved_elem_idx,+ None,+ true,+ )+ .await;+ }+ } else {announce_keyboard_target(&args, pid, xid, resolved_elem_idx, px.zip(py)).await;}let owner = named_session_cursor_key(&args);@@ -8185,6 +8244,8 @@ impl Tool for PressKeyTool {"isolated keys address the exact top-level; first click the child explicitly",);}+ position_named_session_keyboard_cursor(&self.state, &args, pid, xid, None, None, false)+ .await;return isolated_hyprland_action(&args,pid,@@ -8247,6 +8308,18 @@ impl Tool for PressKeyTool {{return error;}+ if px.is_none() {+ position_named_session_keyboard_cursor(+ &self.state,+ &args,+ pid,+ xid,+ resolved_element_index,+ None,+ false,+ )+ .await;+ }return foreground_hyprland_action(&args, pid, xid, action).await;}@@ -8629,6 +8702,8 @@ impl Tool for HotkeyTool {);}}+ position_named_session_keyboard_cursor(&self.state, &args, pid, xid, None, None, false)+ .await;return isolated_hyprland_action(&args,pid,@@ -8703,6 +8778,18 @@ impl Tool for HotkeyTool {{return error;}+ if px.is_none() {+ position_named_session_keyboard_cursor(+ &self.state,+ &args,+ pid,+ xid,+ resolved_element_index,+ None,+ false,+ )+ .await;+ }return foreground_hyprland_action(&args, pid, xid, action).await;}@@ -9496,17 +9583,15 @@ impl Tool for ScrollTool {} else {pixel_target};- return foreground_hyprland_action(- &args,- pid,- xid,- crate::wayland::hyprland_input::Action::Scroll {- point,- direction,- amount,- },- )- .await;+ // `by: "page"` is the documented 3-detent approximation, not an+ // exact viewport; large requests become several wheel packets.+ let actions =+ match crate::wayland::hyprland_input::scroll_actions(point, &direction, amount, by)+ {+ Ok(actions) => actions,+ Err(error) => return foreground_hyprland_refusal(error.to_string()),+ };+ return foreground_hyprland_scroll(&args, pid, xid, actions).await;}if isolated_background {if xid_opt.is_none() {@@ -9523,15 +9608,14 @@ impl Tool for ScrollTool {} else {pixel_target};- crate::wayland::hyprland_input::execute(+ let actions = crate::wayland::hyprland_input::scroll_actions(+ point, &direction, amount, by,+ )?;+ crate::wayland::hyprland_input::execute_scroll(owner,pid,xid,- crate::wayland::hyprland_input::Action::Scroll {- point,- direction,- amount,- },+ actions,cancellation,)}) {diff --git a/libs/cua-driver/rust/crates/platform-linux/src/wayland/hyprland.rs b/libs/cua-driver/rust/crates/platform-linux/src/wayland/hyprland.rsindex ec46d746d4..48e95b40e0 100644--- a/libs/cua-driver/rust/crates/platform-linux/src/wayland/hyprland.rs+++ b/libs/cua-driver/rust/crates/platform-linux/src/wayland/hyprland.rs@@ -35,6 +35,9 @@ struct Client {at: [i32; 2],size: [i32; 2],workspace: Workspace,+ /// Absent on compositors that do not report it; never read as native.+ #[serde(default)]+ xwayland: Option<bool>,/// 0 is the focused client; larger is longer ago. Absent on old builds.#[serde(rename = "focusHistoryID", default)]focus_history: i64,@@ -70,6 +73,9 @@ pub struct Window {pub height: u32,pub workspace: i64,pub visible: bool,+ /// `Some(true)` for XWayland, `Some(false)` for native Wayland, `None`+ /// when the compositor did not report the flag.+ pub xwayland: Option<bool>,hidden: bool,/// Focus recency (0 = focused); the closest thing to z-order Hyprland/// exposes.@@ -316,6 +322,7 @@ fn windows_from_clients(clients: Vec<Client>, active: &HashSet<i64>) -> Result<Vheight,workspace: c.workspace.id,visible: !c.hidden && active.contains(&c.workspace.id),+ xwayland: c.xwayland,hidden: c.hidden,focus_order: c.focus_history,});@@ -453,6 +460,21 @@ fn accessibility_target(windows: &[Window], address: u64, pid: u32) -> Option<Wi.then(|| target.clone())}+/// True only when the compositor positively identifies the exact+/// `(address, pid)` client as native Wayland. A zero address, missing or+/// mismatched window, or an absent/XWayland flag all refuse.+pub fn native_client_attested(address: u64, pid: u32) -> bool {+ list_windows().is_ok_and(|windows| native_attestation(&windows, address, pid))+}++fn native_attestation(windows: &[Window], address: u64, pid: u32) -> bool {+ address != 0+ && windows+ .iter()+ .find(|w| w.address == address)+ .is_some_and(|w| w.pid == pid && w.xwayland == Some(false))+}+/// The legacy PID-only bounds caller has no window identity: allow only a/// single mapped client. Explicit IDs never fall back to this function.pub fn window_for_pid(pid: u32) -> Option<Window> {@@ -534,11 +556,46 @@ mod tests {height: 600,workspace: 1,visible: true,+ xwayland: Some(false),hidden: false,focus_order: 0,}}+ #[test]+ fn native_attestation_requires_exact_address_pid_and_native_flag() {+ let native = window(0x10, 42);+ let mut xwayland = window(0x20, 42);+ xwayland.xwayland = Some(true);+ let mut absent = window(0x30, 42);+ absent.xwayland = None;+ let windows = [native, xwayland, absent];+ assert!(native_attestation(&windows, 0x10, 42));+ assert!(!native_attestation(&windows, 0x20, 42));+ assert!(!native_attestation(&windows, 0x30, 42));+ assert!(!native_attestation(&windows, 0x10, 43));+ assert!(!native_attestation(&windows, 0x40, 42));+ assert!(!native_attestation(&windows, 0, 42));+ }++ #[test]+ fn client_xwayland_flag_is_tri_state() {+ let active = HashSet::from([1]);+ let with = |flag: Option<bool>| {+ let mut c = client("0x10", 42, [800, 600]);+ c.xwayland = flag;+ windows_from_clients(vec![c], &active)+ .unwrap()+ .remove(0)+ .xwayland+ };+ assert_eq!(with(Some(true)), Some(true));+ assert_eq!(with(Some(false)), Some(false));+ assert_eq!(with(None), None);+ // `client()` omits the field entirely: absent must deserialize to None.+ assert_eq!(client("0x10", 42, [800, 600]).xwayland, None);+ }+#[test]fn exact_identity_never_falls_back_to_sibling_or_other_pid() {let windows = [window(0x10, 42), window(0x20, 42)];diff --git a/libs/cua-driver/rust/crates/platform-linux/src/wayland/hyprland_input.rs b/libs/cua-driver/rust/crates/platform-linux/src/wayland/hyprland_input.rsindex 4cdb435308..5f6624f51e 100644--- a/libs/cua-driver/rust/crates/platform-linux/src/wayland/hyprland_input.rs+++ b/libs/cua-driver/rust/crates/platform-linux/src/wayland/hyprland_input.rs@@ -115,6 +115,52 @@ pub(crate) fn text_actions(text: &str) -> Result<Vec<Action>> {.collect()}+/// Wheel detents per `by: "page"` unit. This is the same documented+/// approximation the Windows foreground fallback uses (page = 3 detents); it is+/// not a toolkit-measured viewport fraction, and callers must not treat a page+/// as an exact viewport.+pub(crate) const PAGE_WHEEL_DETENTS: usize = 3;+/// Public scroll `amount` bound (before the page multiplier).+const MAX_SCROLL_AMOUNT: usize = 50;+/// One protocol packet carries at most 100 detents (|value| <= 1000 at 10 per+/// detent). Larger requests are decomposed, never clamped.+const MAX_DETENTS_PER_PACKET: usize = 100;++/// Validate the whole request before dispatching anything, then expand it to+/// wheel packets. `amount` is the public 1..=50 count of lines or pages. A page+/// request that exceeds one packet becomes several consecutive same-direction+/// packets whose detents sum exactly to `amount * PAGE_WHEEL_DETENTS`.+pub(crate) fn scroll_actions(+ point: Option<(f64, f64)>,+ direction: &str,+ amount: usize,+ by: cua_driver_contract::ScrollBy,+) -> Result<Vec<Action>> {+ ensure!(+ (1..=MAX_SCROLL_AMOUNT).contains(&amount),+ "unsupported scroll amount"+ );+ ensure!(+ matches!(direction, "up" | "down" | "left" | "right"),+ "unsupported scroll direction"+ );+ let mut remaining = match by {+ cua_driver_contract::ScrollBy::Line => amount,+ cua_driver_contract::ScrollBy::Page => amount * PAGE_WHEEL_DETENTS,+ };+ let mut actions = Vec::new();+ while remaining > 0 {+ let chunk = remaining.min(MAX_DETENTS_PER_PACKET);+ actions.push(Action::Scroll {+ point,+ direction: direction.to_owned(),+ amount: chunk,+ });+ remaining -= chunk;+ }+ Ok(actions)+}+/// Cancellation belongs to one invocation, never to its session's next call.#[derive(Clone, Default)]pub(crate) struct ActionCancellation(Arc<AtomicBool>);@@ -165,7 +211,8 @@ impl std::fmt::Display for LaneBusy {impl std::error::Error for LaneBusy {}/// A sent action has no trustworthy final reply. The count describes only-/// acknowledged gesture phases (drag start or completed text keys), never a+/// acknowledged gesture phases (drag start, completed text keys, or completed+/// wheel packets of a multi-packet scroll), never a/// total event count or proof that no later events landed.#[derive(Debug)]pub struct DispatchUnknown {@@ -1065,6 +1112,66 @@ pub(crate) fn execute_background_text()}+pub(crate) fn execute_scroll(+ owner: Option<String>,+ pid: u32,+ address: u64,+ actions: Vec<Action>,+ cancellation: ActionCancellation,+) -> Result<Value> {+ execute_scroll_routed(+ owner,+ pid,+ address,+ actions,+ cancellation,+ DeliveryRoute::Background,+ )+}++pub(crate) fn execute_foreground_scroll(+ owner: Option<String>,+ pid: u32,+ address: u64,+ actions: Vec<Action>,+ cancellation: ActionCancellation,+) -> Result<Value> {+ execute_scroll_routed(+ owner,+ pid,+ address,+ actions,+ cancellation,+ DeliveryRoute::Foreground,+ )+}++/// One packet keeps the single-action reply; several run as a paced sequence+/// whose `delivered_count` counts acknowledged wheel packets, not detents.+fn execute_scroll_routed(+ owner: Option<String>,+ pid: u32,+ address: u64,+ actions: Vec<Action>,+ cancellation: ActionCancellation,+ route: DeliveryRoute,+) -> Result<Value> {+ ensure!(+ !actions.is_empty() && actions.iter().all(|a| matches!(a, Action::Scroll { .. })),+ "scroll requires wheel actions"+ );+ let sequence = actions.len() > 1;+ execute_actions_routed(+ owner,+ (pid, address),+ actions,+ None,+ cancellation,+ route,+ sequence,+ )+}+fn execute_text_routed(owner: Option<String>,pid: u32,@@ -1187,6 +1294,11 @@ fn execute_text_actions() -> Result<Value> {let mut delivered = 0u32;let action_count = actions.len();+ // Shared by text keys and wheel packets; only the interruption code differs.+ let interrupted_code = match actions.first() {+ Some(Action::Scroll { .. }) => "scroll_interrupted",+ _ => "text_interrupted",+ };for (index, action) in actions.into_iter().enumerate() {match dispatch(action) {Ok(mut reply) if reply["ok"] == false => {@@ -1214,7 +1326,7 @@ fn execute_text_actions(return Err(error);}return Ok(- json!({"ok":false,"code":"text_interrupted","detail":error.to_string(),+ json!({"ok":false,"code":interrupted_code,"detail":error.to_string(),"effect":"partial","delivery":{"mode":route.mode(),"delivered_count":delivered}}),);}@@ -1262,6 +1374,7 @@ fn terminal_connection_result(value: &Value) -> bool {| "plugin_shutdown"| "generation_exhausted"| "text_interrupted"+ | "scroll_interrupted")))}@@ -1352,6 +1465,116 @@ mod tests {)}+ fn scroll_values(actions: &[Action]) -> Vec<String> {+ actions+ .iter()+ .map(|action| {+ let packet = action.packet(1, TOKEN, 1, 100.0, 100.0).unwrap();+ packet.rsplit(' ').next().unwrap().to_owned()+ })+ .collect()+ }++ #[test]+ fn scroll_line_keeps_ten_units_per_detent_in_each_direction() {+ use cua_driver_contract::ScrollBy::Line;+ for (direction, axis, sign) in [+ ("up", 0, -1),+ ("down", 0, 1),+ ("left", 1, -1),+ ("right", 1, 1),+ ] {+ let actions = scroll_actions(None, direction, 3, Line).unwrap();+ assert_eq!(actions.len(), 1);+ let packet = actions[0].packet(1, TOKEN, 1, 100.0, 100.0).unwrap();+ assert_eq!(+ packet,+ format!("SCROLL 1 {TOKEN} 1 50 50 {axis} {}", 30 * sign)+ );+ }+ }++ #[test]+ fn scroll_page_is_three_detents_per_page_in_each_direction() {+ use cua_driver_contract::ScrollBy::Page;+ for (direction, sign) in [("up", -1), ("down", 1), ("left", -1), ("right", 1)] {+ let actions = scroll_actions(Some((5.0, 6.0)), direction, 2, Page).unwrap();+ assert_eq!(scroll_values(&actions), vec![(60 * sign).to_string()]);+ }+ }++ #[test]+ fn scroll_page_beyond_one_packet_is_decomposed_without_loss() {+ use cua_driver_contract::ScrollBy::{Line, Page};+ // Maximum public amount: 50 lines fit one packet; 50 pages = 150+ // detents = 100 + 50, never clamped.+ assert_eq!(+ scroll_values(&scroll_actions(None, "down", 50, Line).unwrap()),+ vec!["500"]+ );+ let actions = scroll_actions(None, "up", 50, Page).unwrap();+ assert_eq!(scroll_values(&actions), vec!["-1000", "-500"]);+ // The first packet at the protocol's |1000| limit is still valid.+ assert_eq!(+ scroll_values(&scroll_actions(None, "down", 34, Page).unwrap()),+ vec!["1000", "20"]+ );+ assert_eq!(+ scroll_values(&scroll_actions(None, "down", 33, Page).unwrap()),+ vec!["990"]+ );+ }++ #[test]+ fn scroll_rejects_invalid_amount_and_direction_before_any_packet() {+ use cua_driver_contract::ScrollBy::{Line, Page};+ for by in [Line, Page] {+ assert!(scroll_actions(None, "down", 0, by).is_err());+ assert!(scroll_actions(None, "down", 51, by).is_err());+ assert!(scroll_actions(None, "sideways", 1, by).is_err());+ assert!(scroll_actions(None, "", 1, by).is_err());+ }+ // The packet encoder keeps its own protocol bound.+ let over = Action::Scroll {+ point: None,+ direction: "down".into(),+ amount: 101,+ };+ assert!(over.packet(1, TOKEN, 1, 100.0, 100.0).is_err());+ }++ #[test]+ fn multi_packet_scroll_reports_packets_and_interruption_honestly() {+ let actions =+ scroll_actions(None, "down", 50, cua_driver_contract::ScrollBy::Page).unwrap();+ let mut calls = 0;+ let result = execute_text_actions(actions, DeliveryRoute::Foreground, |_| {+ calls += 1;+ Ok(json!({"ok":true,"effect":"unverifiable","route":"primary_foreground"}))+ })+ .unwrap();+ assert_eq!(calls, 2);+ assert_eq!(result["delivery"]["delivered_count"], 2);+ assert_eq!(result["route"], "primary_foreground");++ let actions =+ scroll_actions(None, "down", 50, cua_driver_contract::ScrollBy::Page).unwrap();+ let mut calls = 0;+ let result = execute_text_actions(actions, DeliveryRoute::Background, |_| {+ calls += 1;+ if calls == 1 {+ Ok(json!({"ok":true,"effect":"unverifiable","route":"synthetic_events"}))+ } else {+ anyhow::bail!("cancelled")+ }+ })+ .unwrap();+ assert_eq!(result["code"], "scroll_interrupted");+ assert_eq!(result["effect"], "partial");+ assert_eq!(result["delivery"]["delivered_count"], 1);+ assert!(terminal_connection_result(&result));+ }+#[test]fn foreground_text_attests_each_logical_call_once_and_binds_every_key() {let (mut client, peer) = test_connection();