feat(vom): add typed visual refs and target identity validation

crates/bsk-cli/src/cli/render_error.rs

@@ -40,6 +40,7 @@ use bsk_protocol::ErrorCode;
 pub mod reason {
     pub const AGENT_WINDOW_SCOPE: &str = "agent_window_scope";
     pub const ELEMENT_NOT_VISIBLE: &str = "element_not_visible";
+    pub const REF_KIND_UNSUPPORTED: &str = "ref_kind_unsupported";
     pub const REF_NOT_FOUND: &str = "ref_not_found";
     pub const SELECTOR_NOT_FOUND: &str = "selector_not_found";
     pub const TARGET_NOT_FILLABLE: &str = "target_not_fillable";
@@ -247,6 +248,13 @@ pub fn info_for_error(code: ErrorCode, data: Option<&serde_json::Value>) -> Rend
             ),
             exit_code: base.exit_code,
         },
+        (ErrorCode::Unsupported, reason::REF_KIND_UNSUPPORTED) => RenderInfo {
+            summary: "this tool does not support the ref target type",
+            hint: Some(
+                "use a DOM ref for DOM operations; visual-region refs require an available visual screenshot path",
+            ),
+            exit_code: base.exit_code,
+        },
         (ErrorCode::NotFound, reason::REF_NOT_FOUND) => RenderInfo {
             summary: "snapshot ref was not found for this tab",
             hint: Some("rerun `bsk snapshot` for the current tab and use one of the returned refs"),
@@ -664,6 +672,15 @@ mod tests {
         assert!(info.summary.contains("timed out after browser dispatch"));
     }
 
+    #[test]
+    fn visual_ref_type_error_has_specific_guidance() {
+        let data = serde_json::json!({ "reason": reason::REF_KIND_UNSUPPORTED });
+        let info = info_for_error(ErrorCode::Unsupported, Some(&data));
+        assert!(info.summary.contains("ref target type"));
+        assert!(info.hint.unwrap().contains("DOM ref"));
+        assert_eq!(info.exit_code, info_for(ErrorCode::Unsupported).exit_code);
+    }
+
     #[test]
     fn ref_not_found_overrides_not_found_copy() {
         let data = serde_json::json!({ "reason": reason::REF_NOT_FOUND });