Cursor rule

1---
2description: API design principles and patterns for skia-rs
3globs: ["**/*.rs"]
4alwaysApply: false
5---
6 
7# API Design Principles
8 
9## Skia API Compatibility
10 
11The primary goal is API compatibility with Skia. When implementing a feature:
12 
131. **Reference the original**: Check `skia/` submodule for the C++ implementation
142. **Match signatures**: Function names and parameter order should match Skia
153. **Match semantics**: Behavior should be identical to Skia
164. **Document differences**: If Rust requires a different approach, document it
17 
18## Builder Pattern
19 
20Use builders for complex object construction:
21 
22```rust
23pub struct PathBuilder {
24    path: Path,
25    last_move: Option<Point>,
26}
27 
28impl PathBuilder {
29    pub fn new() -> Self { ... }
30    pub fn move_to(&mut self, x: Scalar, y: Scalar) -> &mut Self { ... }
31    pub fn line_to(&mut self, x: Scalar, y: Scalar) -> &mut Self { ... }
32    pub fn build(self) -> Path { ... }
33}
34```
35 
36## Method Chaining
37 
38Support fluent interfaces where appropriate:
39 
40```rust
41impl Paint {
42    pub fn set_color(&mut self, color: Color4f) -> &mut Self {
43        self.color = color;
44        self
45    }
46 
47    pub fn set_style(&mut self, style: Style) -> &mut Self {
48        self.style = style;
49        self
50    }
51}
52 
53// Usage:
54paint.set_color(Color4f::RED)
55     .set_style(Style::Stroke)
56     .set_stroke_width(2.0);
57```
58 
59## Const Correctness
60 
61- Use `const fn` where possible
62- Define common constants as associated constants
63 
64```rust
65impl Rect {
66    pub const EMPTY: Self = Self { left: 0.0, top: 0.0, right: 0.0, bottom: 0.0 };
67 
68    #[inline]
69    pub const fn new(left: Scalar, top: Scalar, right: Scalar, bottom: Scalar) -> Self {
70        Self { left, top, right, bottom }
71    }
72}
73```
74 
75## Common Patterns
76 
77### Cloning vs Referencing
78 
79- Prefer references for read-only access
80- Clone only when ownership transfer is needed
81- Use `Cow<T>` when clone-on-write is beneficial
82 
83### Option Patterns
84 
85```rust
86// Skia-style: return Option for fallible operations
87pub fn invert(&self) -> Option<Matrix> {
88    let det = self.determinant();
89    if det == 0.0 {
90        return None;
91    }
92    Some(self.compute_inverse(det))
93}
94```
95 
96### Iteration
97 
98```rust
99// Provide iterators for collections
100impl Path {
101    pub fn iter(&self) -> PathIter<'_> {
102        PathIter { path: self, index: 0 }
103    }
104}
105 
106// Make types iterable
107impl<'a> IntoIterator for &'a Path {
108    type Item = PathElement;
109    type IntoIter = PathIter<'a>;
110 
111    fn into_iter(self) -> Self::IntoIter {
112        self.iter()
113    }
114}
115```
116