fret-runtime 0.1.0

Runtime abstractions and scheduling surfaces for host integration in Fret.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

use serde::{Deserialize, Serialize};

/// Quality of cursor/position updates during external OS drag sessions (e.g. file drag hover).
///
/// This is used to express *degradation*, not just availability:
/// a backend may support external drops but not provide reliable per-frame hover coordinates.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum ExternalDragPositionQuality {
    /// External drag is unsupported (or position updates are unavailable).
    None,
    /// The backend provides external drag events, but pointer positions are best-effort / may be
    /// stale or missing (e.g. macOS winit file DnD hover limitations).
    BestEffort,
    /// The backend provides reliable pointer position updates during external drag hover.
    #[default]
    Continuous,
}

impl ExternalDragPositionQuality {
    pub fn as_str(self) -> &'static str {
        match self {
            Self::None => "none",
            Self::BestEffort => "best_effort",
            Self::Continuous => "continuous",
        }
    }

    pub fn clamp_to_available(self, available: Self) -> Self {
        use ExternalDragPositionQuality::*;
        match (self, available) {
            (None, _) => None,
            (_, None) => None,
            (BestEffort, BestEffort | Continuous) => BestEffort,
            (Continuous, Continuous) => Continuous,
            (Continuous, BestEffort) => BestEffort,
        }
    }
}

/// Windowing quality signal: whether the backend can reliably determine which window is under the
/// cursor.
///
/// This is used as a degradation signal for editor-grade multi-window UX (e.g. docking tear-off
/// hover target selection under overlap).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum WindowHoverDetectionQuality {
    /// The backend cannot reliably determine window-under-cursor (or cannot provide global cursor
    /// position updates needed to infer it).
    None,
    /// Best-effort: selection may be stale/missing or ambiguous under overlap.
    BestEffort,
    /// Reliable enough for editor-grade hover selection.
    #[default]
    Reliable,
}

impl WindowHoverDetectionQuality {
    pub fn as_str(self) -> &'static str {
        match self {
            Self::None => "none",
            Self::BestEffort => "best_effort",
            Self::Reliable => "reliable",
        }
    }

    pub fn clamp_to_available(self, available: Self) -> Self {
        use WindowHoverDetectionQuality::*;
        match (self, available) {
            (None, _) => None,
            (_, None) => None,
            (BestEffort, BestEffort | Reliable) => BestEffort,
            (Reliable, Reliable) => Reliable,
            (Reliable, BestEffort) => BestEffort,
        }
    }
}

/// Windowing quality signal: whether programmatic window movement via outer-position requests is
/// reliable enough for "follow cursor" UX.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum WindowSetOuterPositionQuality {
    None,
    BestEffort,
    #[default]
    Reliable,
}

impl WindowSetOuterPositionQuality {
    pub fn as_str(self) -> &'static str {
        match self {
            Self::None => "none",
            Self::BestEffort => "best_effort",
            Self::Reliable => "reliable",
        }
    }

    pub fn clamp_to_available(self, available: Self) -> Self {
        use WindowSetOuterPositionQuality::*;
        match (self, available) {
            (None, _) => None,
            (_, None) => None,
            (BestEffort, BestEffort | Reliable) => BestEffort,
            (Reliable, Reliable) => Reliable,
            (Reliable, BestEffort) => BestEffort,
        }
    }
}

/// Windowing quality signal: whether OS z-level requests (e.g. AlwaysOnTop during drags) behave
/// predictably.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum WindowZLevelQuality {
    None,
    BestEffort,
    #[default]
    Reliable,
}

impl WindowZLevelQuality {
    pub fn as_str(self) -> &'static str {
        match self {
            Self::None => "none",
            Self::BestEffort => "best_effort",
            Self::Reliable => "reliable",
        }
    }

    pub fn clamp_to_available(self, available: Self) -> Self {
        use WindowZLevelQuality::*;
        match (self, available) {
            (None, _) => None,
            (_, None) => None,
            (BestEffort, BestEffort | Reliable) => BestEffort,
            (Reliable, Reliable) => Reliable,
            (Reliable, BestEffort) => BestEffort,
        }
    }
}