Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

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.md
new file mode 100644
index 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.rs
index 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.rs
index 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.rs
index 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_.rs
index 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.rs
index 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<V
height,
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.rs
index 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();