Explain runtime invariants and avoid redundant unwraps

compositor/src/render/backdrop.rs

@@ -108,10 +108,15 @@ fn update_shared<E: Element>(
 ) -> bool {
     // Element queries can read this same backdrop's commit. Snapshot the state,
     // release its lock, then inspect sources. Rendering is the sole writer.
-    let mut backdrop = shared.lock().unwrap().clone();
+    let mut backdrop = shared
+        .lock()
+        .expect("surface rendering state must remain consistent across callbacks")
+        .clone();
     let sources = elements.iter().filter(|element| element.id() != owner);
     let changed = backdrop.update(sources, region, scale);
-    *shared.lock().unwrap() = backdrop;
+    *shared
+        .lock()
+        .expect("surface rendering state must remain consistent across callbacks") = backdrop;
     changed
 }
 

compositor/src/render/capture.rs

@@ -106,7 +106,11 @@ pub(crate) fn capture_window_frame(
         .user_data()
         .get_or_insert_threadsafe(|| Arc::new(CaptureTarget::default()))
         .clone();
-    let reusable = cache.0.lock().unwrap().take();
+    let reusable = cache
+        .0
+        .lock()
+        .expect("the reusable capture texture cache must remain consistent across callbacks")
+        .take();
     let mut snapshot = render_window_texture(
         renderer,
         window,
@@ -159,7 +163,11 @@ pub(crate) fn capture_window_frame(
         return Err("Incomplete window readback".into());
     }
     let pixels = source[..bytes].to_vec();
-    *cache.0.lock().unwrap() = Some(snapshot.texture);
+    *cache
+        .0
+        .lock()
+        .expect("the reusable capture texture cache must remain consistent across callbacks") =
+        Some(snapshot.texture);
 
     Ok(crate::handlers::screenshot::CaptureBuffer {
         width: size.w,

compositor/src/render/materials.rs

@@ -730,7 +730,7 @@ fn panel_matrices(
                 match permutation
                     .iter()
                     .position(|i| *i == old_corner as f32)
-                    .unwrap()
+                    .expect("the corner transform is a permutation containing every source corner")
                 {
                     0 => 5,
                     1 => 4,

compositor/src/render/mod.rs

@@ -222,7 +222,11 @@ impl BlurRenderElement {
         self.geometry = parameters.sample_geometry;
         self.capture_rect = framebuffer_capture_rect(parameters.sample_framebuffer);
         self.uniforms = blur_uniforms(parameters).into();
-        self.backdrop.lock().unwrap().commit.increment();
+        self.backdrop
+            .lock()
+            .expect("surface rendering state must remain consistent across callbacks")
+            .commit
+            .increment();
     }
 }
 
@@ -232,7 +236,10 @@ impl Element for BlurRenderElement {
     }
 
     fn current_commit(&self) -> CommitCounter {
-        self.backdrop.lock().unwrap().commit
+        self.backdrop
+            .lock()
+            .expect("surface rendering state must remain consistent across callbacks")
+            .commit
     }
 
     fn src(&self) -> Rectangle<f64, Buffer> {

compositor/src/render/scene.rs

@@ -561,7 +561,14 @@ pub(super) fn cursor_elements(
                 states
                     .data_map
                     .get::<CursorImageSurfaceData>()
-                    .map(|attributes| attributes.lock().unwrap().hotspot)
+                    .map(|attributes| {
+                        attributes
+                            .lock()
+                            .expect(
+                                "cursor surface attributes must remain consistent across callbacks",
+                            )
+                            .hotspot
+                    })
                     .unwrap_or_default()
             });
             let physical_location =