Skip to main content

qualia_app_contract/
target.rs

1//! Command target and interaction context definitions.
2
3use crate::error::ContractError;
4use crate::id::{validate_finite_f64, DecimalU64};
5use serde::{Deserialize, Serialize};
6
7/// Detailed selection payload within a target.
8#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
9#[serde(tag = "kind", content = "payload", rename_all = "snake_case")]
10pub enum SelectionKind {
11    None,
12    Single(String),
13    Multiple(Vec<String>),
14    Range { start: String, end: String },
15}
16
17/// Normalized pointer hit event data.
18#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
19pub struct PointerHit {
20    pub x: f64,
21    pub y: f64,
22    #[serde(skip_serializing_if = "Option::is_none")]
23    pub pressure: Option<f64>,
24    pub surface_id: String,
25}
26
27impl PointerHit {
28    /// Creates a new instance.
29    pub fn new(x: f64, y: f64, surface_id: impl Into<String>) -> Result<Self, ContractError> {
30        let x = validate_finite_f64(x, "x")?;
31        let y = validate_finite_f64(y, "y")?;
32        Ok(Self {
33            x,
34            y,
35            pressure: None,
36            surface_id: surface_id.into(),
37        })
38    }
39
40    /// Builder — sets pressure.
41    pub fn with_pressure(mut self, pressure: f64) -> Result<Self, ContractError> {
42        let p = validate_finite_f64(pressure, "pressure")?;
43        if !(0.0..=1.0).contains(&p) {
44            return Err(ContractError::MalformedParams("pressure must be between 0.0 and 1.0".into()));
45        }
46        self.pressure = Some(p);
47        Ok(self)
48    }
49}
50
51/// Precise target entity for command execution.
52#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
53pub struct CommandTarget {
54    pub session_id: String,
55    pub document_id: String,
56    pub document_revision: DecimalU64,
57    #[serde(default, skip_serializing_if = "Vec::is_empty")]
58    pub object_ids: Vec<String>,
59    pub selection: SelectionKind,
60    #[serde(skip_serializing_if = "Option::is_none")]
61    pub subtarget: Option<String>,
62}
63
64/// Interaction context encompassing pointer, focus, and hierarchy state.
65#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
66pub struct InteractionContext {
67    pub context_id: String,
68    pub principal_id: String,
69    pub construct_id: String,
70    pub manifold_id: String,
71    pub container_id: String,
72    pub target: CommandTarget,
73    pub focus_origin: String,
74    pub editing_mode: String,
75    #[serde(skip_serializing_if = "Option::is_none")]
76    pub pointer_hit: Option<PointerHit>,
77    pub navigation_depth: u32,
78    pub capability_snapshot_revision: DecimalU64,
79}