feat(extension): add bsk hover and adjust vom to support

crates/bsk-protocol/src/tools/interaction.rs

@@ -85,6 +85,52 @@ pub struct ClickResult {
     pub dialogs: Vec<JavaScriptDialogInfo>,
 }
 
+// ---------------------------------------------------------------------------
+// hover
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct HoverParams {
+    pub session_id: String,
+    /// Optional `@e<N>` ref allocated by the last observation.
+    /// Mutually exclusive with `selector`.
+    #[serde(
+        rename = "ref",
+        alias = "ref_",
+        default,
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub ref_: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub selector: Option<String>,
+    /// Target tab. Defaults to the Agent Window's active tab.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub tab_id: Option<i64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub modifiers: Option<Vec<KeyModifier>>,
+    /// Wait after the mouse move so hover-triggered UI can settle.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[schemars(range(min = 0))]
+    pub settle_ms: Option<u32>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[schemars(range(min = 1))]
+    pub timeout_ms: Option<u32>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct HoverResult {
+    pub tab_id: i64,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub used_ref: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub used_selector: Option<String>,
+    /// Viewport-relative hover coordinates (CSS pixels).
+    pub x: f64,
+    pub y: f64,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub dialogs: Vec<JavaScriptDialogInfo>,
+}
+
 // ---------------------------------------------------------------------------
 // fill
 // ---------------------------------------------------------------------------
@@ -261,6 +307,24 @@ mod tests {
         assert_eq!(p.ref_.as_deref(), Some("e1"));
     }
 
+    #[test]
+    fn hover_params_serialise_ref_field_name() {
+        let p = HoverParams {
+            session_id: "abcd".into(),
+            ref_: Some("@e3".into()),
+            selector: None,
+            tab_id: Some(42),
+            modifiers: Some(vec![KeyModifier::Shift]),
+            settle_ms: Some(200),
+            timeout_ms: Some(5_000),
+        };
+        let v = serde_json::to_value(&p).unwrap();
+        assert_eq!(v.get("ref").and_then(|v| v.as_str()), Some("@e3"));
+        assert!(v.get("ref_").is_none());
+        let round: HoverParams = serde_json::from_value(v).unwrap();
+        assert_eq!(round, p);
+    }
+
     #[test]
     fn modifiers_render_as_lowercase_strings() {
         let v = serde_json::to_value(KeyModifier::Ctrl).unwrap();

crates/bsk-protocol/src/tools/record.rs

@@ -94,6 +94,11 @@ pub enum Step {
         common: StepCommon,
         target: TargetDescriptor,
     },
+    Hover {
+        #[serde(flatten)]
+        common: StepCommon,
+        target: TargetDescriptor,
+    },
     Fill {
         #[serde(flatten)]
         common: StepCommon,