Skip to content

armgit / Cap

Public Imported from GitHub
0

Open source Loom alternative. Beautiful, shareable screen recordings.

52.1 KB
Raw Blame
diff --git a/crates/gpui/src/app.rs b/crates/gpui/src/app.rs
index 900e78a367e2..d0cab13a2cb7 100644
--- a/crates/gpui/src/app.rs
+++ b/crates/gpui/src/app.rs
@@ -1350,6 +1350,11 @@
         self.platform.write_to_clipboard(item)
     }

+    /// Writes data to the platform clipboard, returning an error when the platform cannot accept it.
+    pub fn try_write_to_clipboard(&self, item: ClipboardItem) -> Result<()> {
+        self.platform.try_write_to_clipboard(item)
+    }
+
     /// Reads data from the primary selection buffer.
     /// Only available on Linux.
     #[cfg(any(target_os = "linux", target_os = "freebsd"))]
diff --git a/crates/gpui/src/platform.rs b/crates/gpui/src/platform.rs
index 20600c3eb519..9d92bb46f943 100644
--- a/crates/gpui/src/platform.rs
+++ b/crates/gpui/src/platform.rs
@@ -298,6 +298,9 @@

     fn read_from_clipboard(&self) -> Option<ClipboardItem>;
     fn write_to_clipboard(&self, item: ClipboardItem);
+    fn try_write_to_clipboard(&self, _item: ClipboardItem) -> Result<()> {
+        anyhow::bail!("Writing this clipboard item is unsupported")
+    }

     #[cfg(any(target_os = "linux", target_os = "freebsd"))]
     fn read_from_primary(&self) -> Option<ClipboardItem>;
@@ -812,6 +815,17 @@
         detail: Option<&str>,
         answers: &[PromptButton],
     ) -> Option<oneshot::Receiver<usize>>;
+    /// `None` forbids capture-time hiding because this backend has no visibility fence.
+    fn retained_visibility(&self) -> Option<bool> {
+        None
+    }
+    /// Retains the window and renderer state until the compositor acknowledges the change.
+    fn set_retained_visibility(
+        &self,
+        _visible: bool,
+    ) -> Result<oneshot::Receiver<Result<(u64, bool)>>> {
+        anyhow::bail!("Retained window visibility is unsupported by this backend")
+    }
     fn activate(&self);
     /// Requests that the operating system draw attention to this window.
     fn request_attention(&self) {}
diff --git a/crates/gpui/src/scene.rs b/crates/gpui/src/scene.rs
index afb2171476d5..6cc35624a4e1 100644
--- a/crates/gpui/src/scene.rs
+++ b/crates/gpui/src/scene.rs
@@ -828,6 +828,10 @@
     pub order: DrawOrder,
     pub bounds: Bounds<ScaledPixels>,
     pub content_mask: ContentMask<ScaledPixels>,
+    pub corner_radii: Corners<ScaledPixels>,
+    /// Normalized sub-rect of the source texture to sample, for object-fit
+    /// crops. The full texture is `(0,0)..(1,1)`.
+    pub source_uv: Bounds<f32>,
     #[cfg(target_os = "macos")]
     pub image_buffer: core_video::pixel_buffer::CVPixelBuffer,
 }
diff --git a/crates/gpui/src/window.rs b/crates/gpui/src/window.rs
index 0480dc957438..aabf36147842 100644
--- a/crates/gpui/src/window.rs
+++ b/crates/gpui/src/window.rs
@@ -1517,13 +1517,17 @@
                 // Throttle frame rate based on conditions:
                 // - Thermal pressure (Serious/Critical): cap to ~60fps
                 // - Inactive window (not focused): cap to ~30fps to save energy
+                let will_draw = invalidator.is_dirty() || request_frame_options.force_render;
                 let min_frame_interval = if !request_frame_options.force_render
                     && !request_frame_options.require_presentation
                     && next_frame_callbacks.borrow().is_empty()
                 {
                     None
                 } else if !active.get() {
-                    Some(Duration::from_micros(33333))
+                    // The skip below returns before the dirty check, so without
+                    // this an unrelated pending next-frame callback caps fresh
+                    // content at 30fps -- video playback in an unfocused window.
+                    (!will_draw).then_some(Duration::from_micros(33333))
                 } else if let Some(ThermalState::Critical | ThermalState::Serious) = thermal_state {
                     Some(Duration::from_micros(16667))
                 } else {
@@ -2447,6 +2451,19 @@
         self.platform_window.window_controls()
     }
 
+    /// This is retained state; capture still needs a completed visibility receipt.
+    pub fn retained_visibility(&self) -> Option<bool> {
+        self.platform_window.retained_visibility()
+    }
+
+    /// The receipt acknowledges compositor processing, not physical presentation.
+    pub fn set_retained_visibility(
+        &mut self,
+        visible: bool,
+    ) -> anyhow::Result<futures::channel::oneshot::Receiver<anyhow::Result<(u64, bool)>>> {
+        self.platform_window.set_retained_visibility(visible)
+    }
+
     /// Updates the window's title at the platform level.
     pub fn set_window_title(&mut self, title: &str) {
         self.platform_window.set_title(title);
@@ -4542,16 +4559,56 @@
     /// This method should only be called as part of the paint phase of element drawing.
     #[cfg(target_os = "macos")]
     pub fn paint_surface(&mut self, bounds: Bounds<Pixels>, image_buffer: CVPixelBuffer) {
+        self.paint_surface_fitted(bounds, bounds, Corners::default(), image_buffer);
+    }
+
+    /// [`Self::paint_surface`] for object-fit layouts: paint the `visible`
+    /// rect of a surface whose fitted content box is `fitted` (equal or
+    /// larger, e.g. `ObjectFit::Cover`), cropping via the surface's source
+    /// UVs so `corner_radii` round the element's actual corners — the same
+    /// contract as [`Self::paint_image_fitted`].
+    ///
+    /// This method should only be called as part of the paint phase of element drawing.
+    #[cfg(target_os = "macos")]
+    pub fn paint_surface_fitted(
+        &mut self,
+        visible: Bounds<Pixels>,
+        fitted: Bounds<Pixels>,
+        corner_radii: Corners<Pixels>,
+        image_buffer: CVPixelBuffer,
+    ) {
         use crate::PaintSurface;
 
         self.invalidator.debug_assert_paint();
 
-        let bounds = self.snap_bounds(bounds);
+        let source_uv = if visible == fitted {
+            Bounds {
+                origin: point(0., 0.),
+                size: size(1., 1.),
+            }
+        } else {
+            let fitted_width = f32::from(fitted.size.width).max(1.0);
+            let fitted_height = f32::from(fitted.size.height).max(1.0);
+            Bounds {
+                origin: point(
+                    (f32::from(visible.origin.x) - f32::from(fitted.origin.x)) / fitted_width,
+                    (f32::from(visible.origin.y) - f32::from(fitted.origin.y)) / fitted_height,
+                ),
+                size: size(
+                    f32::from(visible.size.width) / fitted_width,
+                    f32::from(visible.size.height) / fitted_height,
+                ),
+            }
+        };
+        let bounds = self.snap_bounds(visible);
         let content_mask = self.snapped_content_mask();
+        let corner_radii = corner_radii.scale(self.scale_factor());
         self.next_frame.scene.insert_primitive(PaintSurface {
             order: 0,
             bounds,
             content_mask,
+            corner_radii,
+            source_uv,
             image_buffer,
         });
     }
diff --git a/crates/gpui_macos/src/metal_renderer.rs b/crates/gpui_macos/src/metal_renderer.rs
index c93a383c38c6..1d35af12f64b 100644
--- a/crates/gpui_macos/src/metal_renderer.rs
+++ b/crates/gpui_macos/src/metal_renderer.rs
@@ -7,17 +7,18 @@
     quartzcore::AutoresizingMask,
 };
 use gpui::{
-    AtlasTextureId, BackdropBlur, Background, Bounds, ContentMask, DevicePixels, DrawOrder,
-    MonochromeSprite, PaintSurface, Path, Point, PolychromeSprite, PrimitiveBatch, Quad,
-    ScaledPixels, Scene, Shadow, Size, Surface, Underline, point, size,
+    AtlasTextureId, BackdropBlur, Background, Bounds, ContentMask, Corners, DevicePixels,
+    DrawOrder, MonochromeSprite, PaintSurface, Path, Point, PolychromeSprite, PrimitiveBatch, Quad,
+    ScaledPixels, Scene, Shadow, Size, Underline, point, size,
 };
 #[cfg(any(test, feature = "test-support"))]
 use image::RgbaImage;
 
 use core_foundation::base::TCFType;
 use core_video::{
-    metal_texture::CVMetalTextureGetTexture, metal_texture_cache::CVMetalTextureCache,
-    pixel_buffer::kCVPixelFormatType_420YpCbCr8BiPlanarFullRange,
+    metal_texture::{CVMetalTexture, CVMetalTextureGetTexture},
+    metal_texture_cache::CVMetalTextureCache,
+    pixel_buffer::{kCVPixelFormatType_32BGRA, kCVPixelFormatType_420YpCbCr8BiPlanarFullRange},
 };
 use foreign_types::{ForeignType, ForeignTypeRef};
 use metal::{
@@ -48,17 +49,12 @@
 /// out popover close/reopen and brief path-free frames, short enough that a
 /// few seconds of activity reclaims the memory.
 const SCRATCH_RELEASE_AFTER_FRAMES: u32 = 30;
+const SURFACE_ERROR_LOG_INTERVAL: std::time::Duration = std::time::Duration::from_secs(5);
 
 pub(crate) type Context = Arc<Mutex<InstanceBufferPool>>;
 pub(crate) type Renderer = MetalRenderer;
 
-pub(crate) unsafe fn new_renderer(
-    context: self::Context,
-    _native_window: *mut c_void,
-    _native_view: *mut c_void,
-    _bounds: gpui::Size<f32>,
-    transparent: bool,
-) -> Renderer {
+pub(crate) fn new_renderer(context: self::Context, transparent: bool) -> Result<Renderer> {
     MetalRenderer::new(context, transparent)
 }
 
@@ -171,11 +167,13 @@
     path_free_frames: u32,
     /// Last time `COMET_GPU_STATS` logged.
     stats_last_log: Option<std::time::Instant>,
+    surface_error_last_log: Option<std::time::Instant>,
     quads_pipeline_state: metal::RenderPipelineState,
     underlines_pipeline_state: metal::RenderPipelineState,
     monochrome_sprites_pipeline_state: metal::RenderPipelineState,
     polychrome_sprites_pipeline_state: metal::RenderPipelineState,
     surfaces_pipeline_state: metal::RenderPipelineState,
+    bgra_surfaces_pipeline_state: metal::RenderPipelineState,
     unit_vertices: metal::Buffer,
     #[allow(clippy::arc_with_non_send_sync)]
     instance_buffer_pool: Arc<Mutex<InstanceBufferPool>>,
@@ -208,8 +206,11 @@
 
 impl MetalRenderer {
     /// Creates a new MetalRenderer with a CAMetalLayer for window-based rendering.
-    pub fn new(instance_buffer_pool: Arc<Mutex<InstanceBufferPool>>, transparent: bool) -> Self {
-        let device = Self::create_device();
+    pub fn new(
+        instance_buffer_pool: Arc<Mutex<InstanceBufferPool>>,
+        transparent: bool,
+    ) -> Result<Self> {
+        let device = Self::create_device()?;
 
         let layer = metal::MetalLayer::new();
         layer.set_device(&device);
@@ -239,12 +240,12 @@
     /// This renderer can render scenes to images without requiring a CAMetalLayer,
     /// window, or AppKit. Use `render_scene_to_image()` to render scenes.
     #[cfg(any(test, feature = "test-support"))]
-    pub fn new_headless(instance_buffer_pool: Arc<Mutex<InstanceBufferPool>>) -> Self {
-        let device = Self::create_device();
+    pub fn new_headless(instance_buffer_pool: Arc<Mutex<InstanceBufferPool>>) -> Result<Self> {
+        let device = Self::create_device()?;
         Self::new_internal(device, None, true, instance_buffer_pool)
     }
 
-    fn create_device() -> metal::Device {
+    fn create_device() -> Result<metal::Device> {
         // Prefer low‐power integrated GPUs on Intel Mac. On Apple
         // Silicon, there is only ever one GPU, so this is equivalent to
         // `metal::Device::system_default()`.
@@ -252,17 +253,15 @@
             .into_iter()
             .min_by_key(|d| (d.is_removable(), !d.is_low_power()))
         {
-            d
+            Ok(d)
         } else {
             // For some reason `all()` can return an empty list, see https://github.com/zed-industries/zed/issues/37689
             // In that case, we fall back to the system default device.
             log::error!(
                 "Unable to enumerate Metal devices; attempting to use system default device"
             );
-            metal::Device::system_default().unwrap_or_else(|| {
-                log::error!("unable to access a compatible graphics device");
-                std::process::exit(1);
-            })
+            metal::Device::system_default()
+                .ok_or_else(|| anyhow::anyhow!("unable to access a compatible graphics device"))
         }
     }
 
@@ -271,15 +270,8 @@
         layer: Option<metal::MetalLayer>,
         opaque: bool,
         instance_buffer_pool: Arc<Mutex<InstanceBufferPool>>,
-    ) -> Self {
-        #[cfg(feature = "runtime_shaders")]
-        let library = device
-            .new_library_with_source(&SHADERS_SOURCE_FILE, &metal::CompileOptions::new())
-            .expect("error building metal library");
-        #[cfg(not(feature = "runtime_shaders"))]
-        let library = device
-            .new_library_with_data(SHADERS_METALLIB)
-            .expect("error building metal library");
+    ) -> Result<Self> {
+        let library = build_shader_library(&device)?;
 
         fn to_float2_bits(point: PointF) -> u64 {
             let mut output = point.y.to_bits() as u64;
@@ -324,7 +316,7 @@
             "path_rasterization_fragment",
             MTLPixelFormat::BGRA8Unorm,
             PATH_SAMPLE_COUNT,
-        );
+        )?;
         let path_sprites_pipeline_state = build_path_sprite_pipeline_state(
             &device,
             &library,
@@ -332,7 +324,7 @@
             "path_sprite_vertex",
             "path_sprite_fragment",
             MTLPixelFormat::BGRA8Unorm,
-        );
+        )?;
         let shadows_pipeline_state = build_pipeline_state(
             &device,
             &library,
@@ -340,7 +332,7 @@
             "shadow_vertex",
             "shadow_fragment",
             MTLPixelFormat::BGRA8Unorm,
-        );
+        )?;
         // Blending DISABLED: the blur REPLACES the region with the blurred
         // snapshot verbatim (fragments outside the rounded rect discard).
         let backdrop_blur_pipeline_state = build_pipeline_state_no_blend(
@@ -350,7 +342,7 @@
             "backdrop_blur_vertex",
             "backdrop_blur_fragment",
             MTLPixelFormat::BGRA8Unorm,
-        );
+        )?;
         let quads_pipeline_state = build_pipeline_state(
             &device,
             &library,
@@ -358,7 +350,7 @@
             "quad_vertex",
             "quad_fragment",
             MTLPixelFormat::BGRA8Unorm,
-        );
+        )?;
         let underlines_pipeline_state = build_pipeline_state(
             &device,
             &library,
@@ -366,7 +358,7 @@
             "underline_vertex",
             "underline_fragment",
             MTLPixelFormat::BGRA8Unorm,
-        );
+        )?;
         let monochrome_sprites_pipeline_state = build_pipeline_state(
             &device,
             &library,
@@ -374,7 +366,7 @@
             "monochrome_sprite_vertex",
             "monochrome_sprite_fragment",
             MTLPixelFormat::BGRA8Unorm,
-        );
+        )?;
         let polychrome_sprites_pipeline_state = build_pipeline_state(
             &device,
             &library,
@@ -382,7 +374,7 @@
             "polychrome_sprite_vertex",
             "polychrome_sprite_fragment",
             MTLPixelFormat::BGRA8Unorm,
-        );
+        )?;
         let surfaces_pipeline_state = build_pipeline_state(
             &device,
             &library,
@@ -390,14 +382,24 @@
             "surface_vertex",
             "surface_fragment",
             MTLPixelFormat::BGRA8Unorm,
-        );
+        )?;
+        let bgra_surfaces_pipeline_state = build_pipeline_state(
+            &device,
+            &library,
+            "bgra_surfaces",
+            "surface_vertex",
+            "surface_bgra_fragment",
+            MTLPixelFormat::BGRA8Unorm,
+        )?;
 
         let command_queue = device.new_command_queue();
         let sprite_atlas = Arc::new(MetalAtlas::new(device.clone(), is_apple_gpu));
-        let core_video_texture_cache =
-            CVMetalTextureCache::new(None, device.clone(), None).unwrap();
-
-        Self {
+        let core_video_texture_cache = CVMetalTextureCache::new(None, device.clone(), None)
+            .map_err(|status| {
+                anyhow::anyhow!("failed to create Core Video Metal texture cache: {status}")
+            })?;
+
+        Ok(Self {
             device,
             layer,
             presents_with_transaction: false,
@@ -415,11 +417,13 @@
             blur_free_frames: 0,
             path_free_frames: 0,
             stats_last_log: None,
+            surface_error_last_log: None,
             quads_pipeline_state,
             underlines_pipeline_state,
             monochrome_sprites_pipeline_state,
             polychrome_sprites_pipeline_state,
             surfaces_pipeline_state,
+            bgra_surfaces_pipeline_state,
             unit_vertices,
             instance_buffer_pool,
             sprite_atlas,
@@ -429,7 +433,7 @@
             path_sample_count: PATH_SAMPLE_COUNT,
             #[cfg(any(test, feature = "test-support"))]
             headless_render_target: None,
-        }
+        })
     }
 
     pub fn layer(&self) -> Option<&metal::MetalLayerRef> {
@@ -486,9 +490,13 @@
             self.path_intermediate_msaa_texture = None;
             return;
         }
-        if self.path_intermediate_texture.as_ref().is_some_and(|texture| {
-            texture.width() == size.width.0 as u64 && texture.height() == size.height.0 as u64
-        }) {
+        if self
+            .path_intermediate_texture
+            .as_ref()
+            .is_some_and(|texture| {
+                texture.width() == size.width.0 as u64 && texture.height() == size.height.0 as u64
+            })
+        {
             return;
         }
 
@@ -919,6 +927,7 @@
         let command_buffer = command_queue.new_command_buffer();
         let alpha = if self.opaque { 1. } else { 0. };
         let mut instance_offset = 0;
+        let mut retained_surface_textures = CommandBufferResources::default();
 
         // Big scratch textures are only worth holding while they're in use:
         // after a run of frames that don't need them, drop them and let the
@@ -1139,6 +1148,7 @@
                     &mut instance_offset,
                     viewport_size,
                     command_encoder,
+                    &mut retained_surface_textures,
                 ),
                 PrimitiveBatch::SubpixelSprites { .. } => unreachable!(),
             };
@@ -1170,6 +1180,8 @@
         self.instance_buffer_pool.lock().note_usage(instance_offset);
         self.maybe_log_gpu_stats();
 
+        retained_surface_textures.retain_until_completion(command_buffer);
+
         Ok(command_buffer.to_owned())
     }
 
@@ -1193,9 +1205,7 @@
         self.stats_last_log = Some(now);
 
         let texture_bytes = |texture: &Option<metal::Texture>| {
-            texture
-                .as_ref()
-                .map_or(0, |t| t.width() * t.height() * 4)
+            texture.as_ref().map_or(0, |t| t.width() * t.height() * 4)
         };
         let backdrop_bytes =
             texture_bytes(&self.backdrop_scratch) + texture_bytes(&self.backdrop_blurred);
@@ -1382,8 +1392,7 @@
             }
         }
         let kernel: *mut objc::runtime::Object = unsafe {
-            let alloc: *mut objc::runtime::Object =
-                msg_send![class!(MPSImageGaussianBlur), alloc];
+            let alloc: *mut objc::runtime::Object = msg_send![class!(MPSImageGaussianBlur), alloc];
             let kernel: *mut objc::runtime::Object = msg_send![
                 alloc,
                 initWithDevice: self.device.as_ptr() as *mut objc::runtime::Object
@@ -1441,8 +1450,10 @@
             mem::size_of_val(&source_rect) as u64,
             source_rect.as_ptr() as *const _,
         );
-        command_encoder
-            .set_fragment_texture(BackdropBlurInputIndex::SourceTexture as u64, Some(source_texture));
+        command_encoder.set_fragment_texture(
+            BackdropBlurInputIndex::SourceTexture as u64,
+            Some(source_texture),
+        );
 
         let blur_bytes_len = mem::size_of_val(blurs);
         let buffer_contents =
@@ -1894,8 +1905,8 @@
         instance_offset: &mut usize,
         viewport_size: Size<DevicePixels>,
         command_encoder: &metal::RenderCommandEncoderRef,
+        retained_surface_textures: &mut CommandBufferResources<CVMetalTexture>,
     ) -> bool {
-        command_encoder.set_render_pipeline_state(&self.surfaces_pipeline_state);
         command_encoder.set_vertex_buffer(
             SurfaceInputIndex::Vertices as u64,
             Some(&self.unit_vertices),
@@ -1913,41 +1924,112 @@
                 DevicePixels::from(surface.image_buffer.get_height() as i32),
             );
 
-            assert_eq!(
-                surface.image_buffer.get_pixel_format(),
-                kCVPixelFormatType_420YpCbCr8BiPlanarFullRange
-            );
-
-            let y_texture = self
-                .core_video_texture_cache
-                .create_texture_from_image(
+            let pixel_format = surface.image_buffer.get_pixel_format();
+            if pixel_format == kCVPixelFormatType_420YpCbCr8BiPlanarFullRange {
+                let y_texture = match self.core_video_texture_cache.create_texture_from_image(
                     surface.image_buffer.as_concrete_TypeRef(),
                     None,
                     MTLPixelFormat::R8Unorm,
                     surface.image_buffer.get_width_of_plane(0),
                     surface.image_buffer.get_height_of_plane(0),
                     0,
-                )
-                .unwrap();
-            let cb_cr_texture = self
-                .core_video_texture_cache
-                .create_texture_from_image(
+                ) {
+                    Ok(texture) => texture,
+                    Err(status) => {
+                        self.log_surface_texture_error(format_args!(
+                            "failed to create Metal luma texture for surface frame: {status}"
+                        ));
+                        continue;
+                    }
+                };
+                let cb_cr_texture = match self.core_video_texture_cache.create_texture_from_image(
                     surface.image_buffer.as_concrete_TypeRef(),
                     None,
                     MTLPixelFormat::RG8Unorm,
                     surface.image_buffer.get_width_of_plane(1),
                     surface.image_buffer.get_height_of_plane(1),
                     1,
-                )
-                .unwrap();
+                ) {
+                    Ok(texture) => texture,
+                    Err(status) => {
+                        self.log_surface_texture_error(format_args!(
+                            "failed to create Metal chroma texture for surface frame: {status}"
+                        ));
+                        continue;
+                    }
+                };
+                let y_metal_texture =
+                    unsafe { CVMetalTextureGetTexture(y_texture.as_concrete_TypeRef()) };
+                let cb_cr_metal_texture =
+                    unsafe { CVMetalTextureGetTexture(cb_cr_texture.as_concrete_TypeRef()) };
+                if y_metal_texture.is_null() || cb_cr_metal_texture.is_null() {
+                    self.log_surface_texture_error(format_args!(
+                        "Core Video returned a null Metal texture for surface frame"
+                    ));
+                    continue;
+                }
+
+                command_encoder.set_render_pipeline_state(&self.surfaces_pipeline_state);
+                command_encoder.set_fragment_texture(SurfaceInputIndex::YTexture as u64, unsafe {
+                    Some(metal::TextureRef::from_ptr(y_metal_texture as *mut _))
+                });
+                command_encoder
+                    .set_fragment_texture(SurfaceInputIndex::CbCrTexture as u64, unsafe {
+                        Some(metal::TextureRef::from_ptr(cb_cr_metal_texture as *mut _))
+                    });
+                retained_surface_textures.push(y_texture);
+                retained_surface_textures.push(cb_cr_texture);
+            } else if pixel_format == kCVPixelFormatType_32BGRA {
+                let color_texture = match self.core_video_texture_cache.create_texture_from_image(
+                    surface.image_buffer.as_concrete_TypeRef(),
+                    None,
+                    MTLPixelFormat::BGRA8Unorm,
+                    surface.image_buffer.get_width(),
+                    surface.image_buffer.get_height(),
+                    0,
+                ) {
+                    Ok(texture) => texture,
+                    Err(status) => {
+                        self.log_surface_texture_error(format_args!(
+                            "failed to create Metal BGRA texture for surface frame: {status}"
+                        ));
+                        continue;
+                    }
+                };
+                let metal_texture =
+                    unsafe { CVMetalTextureGetTexture(color_texture.as_concrete_TypeRef()) };
+                if metal_texture.is_null() {
+                    self.log_surface_texture_error(format_args!(
+                        "Core Video returned a null Metal texture for surface frame"
+                    ));
+                    continue;
+                }
+
+                command_encoder.set_render_pipeline_state(&self.bgra_surfaces_pipeline_state);
+                command_encoder.set_fragment_texture(SurfaceInputIndex::YTexture as u64, unsafe {
+                    Some(metal::TextureRef::from_ptr(metal_texture as *mut _))
+                });
+                retained_surface_textures.push(color_texture);
+            } else {
+                self.log_surface_texture_error(format_args!(
+                    "unsupported surface pixel format: {pixel_format:#x}"
+                ));
+                continue;
+            }
 
             align_offset(instance_offset);
-            let next_offset = *instance_offset + mem::size_of::<Surface>();
+            let next_offset = *instance_offset + mem::size_of::<SurfaceBounds>();
             if next_offset > instance_buffer.size {
                 return false;
             }
 
             command_encoder.set_vertex_buffer(
+                SurfaceInputIndex::Surfaces as u64,
+                Some(&instance_buffer.metal_buffer),
+                *instance_offset as u64,
+            );
+            // The fragment reads corner radii from the same instance record.
+            command_encoder.set_fragment_buffer(
                 SurfaceInputIndex::Surfaces as u64,
                 Some(&instance_buffer.metal_buffer),
                 *instance_offset as u64,
@@ -1957,15 +2039,6 @@
                 mem::size_of_val(&texture_size) as u64,
                 &texture_size as *const Size<DevicePixels> as *const _,
             );
-            // let y_texture = y_texture.get_texture().unwrap().
-            command_encoder.set_fragment_texture(SurfaceInputIndex::YTexture as u64, unsafe {
-                let texture = CVMetalTextureGetTexture(y_texture.as_concrete_TypeRef());
-                Some(metal::TextureRef::from_ptr(texture as *mut _))
-            });
-            command_encoder.set_fragment_texture(SurfaceInputIndex::CbCrTexture as u64, unsafe {
-                let texture = CVMetalTextureGetTexture(cb_cr_texture.as_concrete_TypeRef());
-                Some(metal::TextureRef::from_ptr(texture as *mut _))
-            });
 
             unsafe {
                 let buffer_contents = (instance_buffer.metal_buffer.contents() as *mut u8)
@@ -1976,6 +2049,8 @@
                     SurfaceBounds {
                         bounds: surface.bounds,
                         content_mask: surface.content_mask,
+                        corner_radii: surface.corner_radii,
+                        source_uv: surface.source_uv,
                     },
                 );
             }
@@ -1985,6 +2060,56 @@
         }
         true
     }
+
+    fn log_surface_texture_error(&mut self, error: std::fmt::Arguments<'_>) {
+        let now = std::time::Instant::now();
+        if !surface_error_log_due(self.surface_error_last_log, now) {
+            return;
+        }
+        self.surface_error_last_log = Some(now);
+        log::error!("{error}");
+    }
+}
+
+struct CommandBufferResources<T> {
+    resources: Vec<T>,
+}
+
+impl<T> Default for CommandBufferResources<T> {
+    fn default() -> Self {
+        Self {
+            resources: Vec::new(),
+        }
+    }
+}
+
+impl<T> CommandBufferResources<T> {
+    fn push(&mut self, resource: T) {
+        self.resources.push(resource);
+    }
+}
+
+impl<T: 'static> CommandBufferResources<T> {
+    fn retain_until_completion(self, command_buffer: &metal::CommandBufferRef) {
+        if self.resources.is_empty() {
+            return;
+        }
+
+        // Command encoders retain MTLTexture, but Core Video may recycle its
+        // cache-managed backing unless the CVMetalTexture wrapper also survives.
+        let resources = Cell::new(Some(self.resources));
+        let block = ConcreteBlock::new(move |_| {
+            drop(resources.take());
+        });
+        let block = block.copy();
+        command_buffer.add_completed_handler(&block);
+    }
+}
+
+fn surface_error_log_due(last_log: Option<std::time::Instant>, now: std::time::Instant) -> bool {
+    last_log.is_none_or(|last_log| {
+        now.saturating_duration_since(last_log) >= SURFACE_ERROR_LOG_INTERVAL
+    })
 }
 
 fn new_command_encoder_for_texture<'a>(
@@ -2014,6 +2139,21 @@
     command_encoder
 }
 
+fn build_shader_library(device: &metal::DeviceRef) -> Result<metal::Library> {
+    #[cfg(feature = "runtime_shaders")]
+    {
+        device
+            .new_library_with_source(SHADERS_SOURCE_FILE, &metal::CompileOptions::new())
+            .map_err(|error| anyhow::anyhow!("failed to build Metal shader library: {error}"))
+    }
+    #[cfg(not(feature = "runtime_shaders"))]
+    {
+        device
+            .new_library_with_data(SHADERS_METALLIB)
+            .map_err(|error| anyhow::anyhow!("failed to load Metal shader library: {error}"))
+    }
+}
+
 fn build_pipeline_state(
     device: &metal::DeviceRef,
     library: &metal::LibraryRef,
@@ -2021,19 +2161,30 @@
     vertex_fn_name: &str,
     fragment_fn_name: &str,
     pixel_format: metal::MTLPixelFormat,
-) -> metal::RenderPipelineState {
+) -> Result<metal::RenderPipelineState> {
     let vertex_fn = library
         .get_function(vertex_fn_name, None)
-        .expect("error locating vertex function");
+        .map_err(|error| {
+            anyhow::anyhow!(
+                "failed to locate Metal vertex function {vertex_fn_name} for {label}: {error}"
+            )
+        })?;
     let fragment_fn = library
         .get_function(fragment_fn_name, None)
-        .expect("error locating fragment function");
+        .map_err(|error| {
+            anyhow::anyhow!(
+                "failed to locate Metal fragment function {fragment_fn_name} for {label}: {error}"
+            )
+        })?;
 
     let descriptor = metal::RenderPipelineDescriptor::new();
     descriptor.set_label(label);
     descriptor.set_vertex_function(Some(vertex_fn.as_ref()));
     descriptor.set_fragment_function(Some(fragment_fn.as_ref()));
-    let color_attachment = descriptor.color_attachments().object_at(0).unwrap();
+    let color_attachment = descriptor
+        .color_attachments()
+        .object_at(0)
+        .ok_or_else(|| anyhow::anyhow!("Metal pipeline {label} has no color attachment"))?;
     color_attachment.set_pixel_format(pixel_format);
     color_attachment.set_blending_enabled(true);
     color_attachment.set_rgb_blend_operation(metal::MTLBlendOperation::Add);
@@ -2050,7 +2201,7 @@
 
     device
         .new_render_pipeline_state(&descriptor)
-        .expect("could not create render pipeline state")
+        .map_err(|error| anyhow::anyhow!("failed to create Metal pipeline {label}: {error}"))
 }
 
 fn build_pipeline_state_no_blend(
@@ -2060,25 +2211,36 @@
     vertex_fn_name: &str,
     fragment_fn_name: &str,
     pixel_format: metal::MTLPixelFormat,
-) -> metal::RenderPipelineState {
+) -> Result<metal::RenderPipelineState> {
     let vertex_fn = library
         .get_function(vertex_fn_name, None)
-        .expect("error locating vertex function");
+        .map_err(|error| {
+            anyhow::anyhow!(
+                "failed to locate Metal vertex function {vertex_fn_name} for {label}: {error}"
+            )
+        })?;
     let fragment_fn = library
         .get_function(fragment_fn_name, None)
-        .expect("error locating fragment function");
+        .map_err(|error| {
+            anyhow::anyhow!(
+                "failed to locate Metal fragment function {fragment_fn_name} for {label}: {error}"
+            )
+        })?;
 
     let descriptor = metal::RenderPipelineDescriptor::new();
     descriptor.set_label(label);
     descriptor.set_vertex_function(Some(vertex_fn.as_ref()));
     descriptor.set_fragment_function(Some(fragment_fn.as_ref()));
-    let color_attachment = descriptor.color_attachments().object_at(0).unwrap();
+    let color_attachment = descriptor
+        .color_attachments()
+        .object_at(0)
+        .ok_or_else(|| anyhow::anyhow!("Metal pipeline {label} has no color attachment"))?;
     color_attachment.set_pixel_format(pixel_format);
     color_attachment.set_blending_enabled(false);
 
     device
         .new_render_pipeline_state(&descriptor)
-        .expect("could not create render pipeline state")
+        .map_err(|error| anyhow::anyhow!("failed to create Metal pipeline {label}: {error}"))
 }
 
 /// The draw order of a batch's first primitive — where the backdrop-blur
@@ -2107,19 +2269,30 @@
     vertex_fn_name: &str,
     fragment_fn_name: &str,
     pixel_format: metal::MTLPixelFormat,
-) -> metal::RenderPipelineState {
+) -> Result<metal::RenderPipelineState> {
     let vertex_fn = library
         .get_function(vertex_fn_name, None)
-        .expect("error locating vertex function");
+        .map_err(|error| {
+            anyhow::anyhow!(
+                "failed to locate Metal vertex function {vertex_fn_name} for {label}: {error}"
+            )
+        })?;
     let fragment_fn = library
         .get_function(fragment_fn_name, None)
-        .expect("error locating fragment function");
+        .map_err(|error| {
+            anyhow::anyhow!(
+                "failed to locate Metal fragment function {fragment_fn_name} for {label}: {error}"
+            )
+        })?;
 
     let descriptor = metal::RenderPipelineDescriptor::new();
     descriptor.set_label(label);
     descriptor.set_vertex_function(Some(vertex_fn.as_ref()));
     descriptor.set_fragment_function(Some(fragment_fn.as_ref()));
-    let color_attachment = descriptor.color_attachments().object_at(0).unwrap();
+    let color_attachment = descriptor
+        .color_attachments()
+        .object_at(0)
+        .ok_or_else(|| anyhow::anyhow!("Metal pipeline {label} has no color attachment"))?;
     color_attachment.set_pixel_format(pixel_format);
     color_attachment.set_blending_enabled(true);
     color_attachment.set_rgb_blend_operation(metal::MTLBlendOperation::Add);
@@ -2133,7 +2306,7 @@
 
     device
         .new_render_pipeline_state(&descriptor)
-        .expect("could not create render pipeline state")
+        .map_err(|error| anyhow::anyhow!("failed to create Metal pipeline {label}: {error}"))
 }
 
 fn build_path_rasterization_pipeline_state(
@@ -2144,13 +2317,21 @@
     fragment_fn_name: &str,
     pixel_format: metal::MTLPixelFormat,
     path_sample_count: u32,
-) -> metal::RenderPipelineState {
+) -> Result<metal::RenderPipelineState> {
     let vertex_fn = library
         .get_function(vertex_fn_name, None)
-        .expect("error locating vertex function");
+        .map_err(|error| {
+            anyhow::anyhow!(
+                "failed to locate Metal vertex function {vertex_fn_name} for {label}: {error}"
+            )
+        })?;
     let fragment_fn = library
         .get_function(fragment_fn_name, None)
-        .expect("error locating fragment function");
+        .map_err(|error| {
+            anyhow::anyhow!(
+                "failed to locate Metal fragment function {fragment_fn_name} for {label}: {error}"
+            )
+        })?;
 
     let descriptor = metal::RenderPipelineDescriptor::new();
     descriptor.set_label(label);
@@ -2160,7 +2341,10 @@
         descriptor.set_raster_sample_count(path_sample_count as _);
         descriptor.set_alpha_to_coverage_enabled(false);
     }
-    let color_attachment = descriptor.color_attachments().object_at(0).unwrap();
+    let color_attachment = descriptor
+        .color_attachments()
+        .object_at(0)
+        .ok_or_else(|| anyhow::anyhow!("Metal pipeline {label} has no color attachment"))?;
     color_attachment.set_pixel_format(pixel_format);
     color_attachment.set_blending_enabled(true);
     color_attachment.set_rgb_blend_operation(metal::MTLBlendOperation::Add);
@@ -2172,7 +2356,7 @@
 
     device
         .new_render_pipeline_state(&descriptor)
-        .expect("could not create render pipeline state")
+        .map_err(|error| anyhow::anyhow!("failed to create Metal pipeline {label}: {error}"))
 }
 
 // Align to multiples of 256 make Metal happy.
@@ -2243,11 +2427,13 @@
     pub bounds: Bounds<ScaledPixels>,
 }
 
-#[derive(Clone, Debug, Eq, PartialEq)]
+#[derive(Clone, Debug, PartialEq)]
 #[repr(C)]
 pub struct SurfaceBounds {
     pub bounds: Bounds<ScaledPixels>,
     pub content_mask: ContentMask<ScaledPixels>,
+    pub corner_radii: Corners<ScaledPixels>,
+    pub source_uv: Bounds<f32>,
 }
 
 #[cfg(any(test, feature = "test-support"))]
@@ -2257,10 +2443,10 @@
 
 #[cfg(any(test, feature = "test-support"))]
 impl MetalHeadlessRenderer {
-    pub fn new() -> Self {
+    pub fn new() -> Result<Self> {
         let instance_buffer_pool = Arc::new(Mutex::new(InstanceBufferPool::default()));
-        let renderer = MetalRenderer::new_headless(instance_buffer_pool);
-        Self { renderer }
+        let renderer = MetalRenderer::new_headless(instance_buffer_pool)?;
+        Ok(Self { renderer })
     }
 }
 
@@ -2280,6 +2466,85 @@
 
     fn sprite_atlas(&self) -> Arc<dyn gpui::PlatformAtlas> {
         self.renderer.sprite_atlas().clone()
+    }
+}
+
+#[cfg(test)]
+mod renderer_hardening_tests {
+    use super::*;
+    use std::sync::atomic::{AtomicBool, Ordering};
+
+    struct DropProbe(Arc<AtomicBool>);
+
+    impl Drop for DropProbe {
+        fn drop(&mut self) {
+            self.0.store(true, Ordering::Release);
+        }
+    }
+
+    #[test]
+    fn missing_pipeline_function_returns_error() -> Result<()> {
+        let Some(device) = metal::Device::system_default() else {
+            return Ok(());
+        };
+        let library = build_shader_library(&device)?;
+        let result = build_pipeline_state(
+            &device,
+            &library,
+            "invalid_test_pipeline",
+            "missing_vertex_function",
+            "quad_fragment",
+            MTLPixelFormat::BGRA8Unorm,
+        );
+
+        let Err(error) = result else {
+            anyhow::bail!("pipeline unexpectedly accepted a missing vertex function");
+        };
+        assert!(
+            error.to_string().contains("missing_vertex_function"),
+            "unexpected pipeline error: {error:#}"
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn command_buffer_resources_follow_completion_or_scope_lifetime() {
+        let Some(device) = metal::Device::system_default() else {
+            return;
+        };
+        let command_queue = device.new_command_queue();
+
+        let completed_drop = Arc::new(AtomicBool::new(false));
+        let command_buffer = command_queue.new_command_buffer();
+        let mut completed_resources = CommandBufferResources::default();
+        completed_resources.push(DropProbe(completed_drop.clone()));
+        completed_resources.retain_until_completion(command_buffer);
+        assert!(!completed_drop.load(Ordering::Acquire));
+        command_buffer.commit();
+        command_buffer.wait_until_completed();
+        assert!(completed_drop.load(Ordering::Acquire));
+
+        let unsubmitted_drop = Arc::new(AtomicBool::new(false));
+        let mut unsubmitted_resources = CommandBufferResources::default();
+        unsubmitted_resources.push(DropProbe(unsubmitted_drop.clone()));
+        assert!(!unsubmitted_drop.load(Ordering::Acquire));
+        drop(unsubmitted_resources);
+        assert!(unsubmitted_drop.load(Ordering::Acquire));
+    }
+
+    #[test]
+    fn surface_error_logging_is_throttled() {
+        let last_log = std::time::Instant::now();
+        let before_interval = last_log
+            .checked_add(SURFACE_ERROR_LOG_INTERVAL / 2)
+            .expect("test instant overflowed");
+        let at_interval = last_log
+            .checked_add(SURFACE_ERROR_LOG_INTERVAL)
+            .expect("test instant overflowed");
+
+        assert!(surface_error_log_due(None, last_log));
+        assert!(!surface_error_log_due(Some(last_log), before_interval));
+        assert!(surface_error_log_due(Some(last_log), at_interval));
     }
 }
 
@@ -2369,7 +2634,8 @@
     fn render(scene: &mut Scene) -> RgbaImage {
         scene.finish();
         let mut renderer =
-            MetalRenderer::new_headless(Arc::new(Mutex::new(InstanceBufferPool::default())));
+            MetalRenderer::new_headless(Arc::new(Mutex::new(InstanceBufferPool::default())))
+                .expect("failed to initialize headless renderer");
         renderer
             .render_scene_to_image(scene, size(DevicePixels(VIEW_W), DevicePixels(VIEW_H)))
             .expect("render_scene_to_image failed")
@@ -2451,7 +2717,10 @@
         let b = render(&mut scene);
 
         let diff = max_abs_diff(&a, &b, 0, 168, 152, 312);
-        assert!(diff <= 3, "vignette or shift at window edge: max diff {diff}");
+        assert!(
+            diff <= 3,
+            "vignette or shift at window edge: max diff {diff}"
+        );
     }
 
     #[test]
diff --git a/crates/gpui_macos/src/platform.rs b/crates/gpui_macos/src/platform.rs
index b25067935e5f..c60ef0b4ec97 100644
--- a/crates/gpui_macos/src/platform.rs
+++ b/crates/gpui_macos/src/platform.rs
@@ -666,7 +666,7 @@
             foreground_executor,
             background_executor,
             renderer_context,
-        )))
+        )?))
     }
 
     fn window_appearance(&self) -> WindowAppearance {
diff --git a/crates/gpui_macos/src/shaders.metal b/crates/gpui_macos/src/shaders.metal
index 97bad184dc58..e087c0dc8a54 100644
--- a/crates/gpui_macos/src/shaders.metal
+++ b/crates/gpui_macos/src/shaders.metal
@@ -880,16 +880,30 @@
       to_device_position(unit_vertex, surface.bounds, viewport_size);
   float4 clip_distance = distance_from_clip_rect(unit_vertex, surface.bounds,
                                                  surface.content_mask.bounds);
-  // We are going to copy the whole texture, so the texture position corresponds
-  // to the current vertex of the unit triangle.
-  float2 texture_position = unit_vertex;
+  float2 texture_position =
+      float2(surface.source_uv.origin.x, surface.source_uv.origin.y) +
+      unit_vertex * float2(surface.source_uv.size.width,
+                           surface.source_uv.size.height);
   return SurfaceVertexOutput{
       device_position,
       texture_position,
       {clip_distance.x, clip_distance.y, clip_distance.z, clip_distance.w}};
 }
 
+float surface_corner_alpha(float2 position, SurfaceBounds surface) {
+  float max_radius = max(
+      max(surface.corner_radii.top_left, surface.corner_radii.top_right),
+      max(surface.corner_radii.bottom_left, surface.corner_radii.bottom_right));
+  if (max_radius <= 0.) {
+    return 1.;
+  }
+  float distance = quad_sdf(position, surface.bounds, surface.corner_radii);
+  return saturate(0.5 - distance);
+}
+
 fragment float4 surface_fragment(SurfaceFragmentInput input [[stage_in]],
+                                 constant SurfaceBounds *surfaces
+                                 [[buffer(SurfaceInputIndex_Surfaces)]],
                                  texture2d<float> y_texture
                                  [[texture(SurfaceInputIndex_YTexture)]],
                                  texture2d<float> cb_cr_texture
@@ -904,7 +918,21 @@
       y_texture.sample(texture_sampler, input.texture_position).r,
       cb_cr_texture.sample(texture_sampler, input.texture_position).rg, 1.0);
 
-  return ycbcrToRGBTransform * ycbcr;
+  float4 color = ycbcrToRGBTransform * ycbcr;
+  color.a *= surface_corner_alpha(input.position.xy, surfaces[0]);
+  return color;
+}
+
+fragment float4 surface_bgra_fragment(SurfaceFragmentInput input [[stage_in]],
+                                      constant SurfaceBounds *surfaces
+                                      [[buffer(SurfaceInputIndex_Surfaces)]],
+                                      texture2d<float> color_texture
+                                      [[texture(SurfaceInputIndex_YTexture)]]) {
+  constexpr sampler texture_sampler(mag_filter::linear, min_filter::linear);
+  float4 color = float4(
+      color_texture.sample(texture_sampler, input.texture_position).rgb, 1.0);
+  color.a *= surface_corner_alpha(input.position.xy, surfaces[0]);
+  return color;
 }
 
 float4 hsla_to_rgba(Hsla hsla) {
diff --git a/crates/gpui_macos/src/window.rs b/crates/gpui_macos/src/window.rs
index 8a3aa5ea067d..f5b2c1a52a82 100644
--- a/crates/gpui_macos/src/window.rs
+++ b/crates/gpui_macos/src/window.rs
@@ -4,7 +4,6 @@
     kTISPropertyInputSourceIsASCIICapable, kTISPropertyInputSourceType, kTISTypeKeyboardInputMode,
     ns_string, renderer,
 };
-#[cfg(any(test, feature = "test-support"))]
 use anyhow::Result;
 use block::ConcreteBlock;
 use cocoa::{
@@ -773,7 +772,9 @@
         foreground_executor: ForegroundExecutor,
         background_executor: BackgroundExecutor,
         renderer_context: renderer::Context,
-    ) -> Self {
+    ) -> Result<Self> {
+        let renderer =
+            objc::rc::autoreleasepool(|| renderer::new_renderer(renderer_context, false))?;
         unsafe {
             let pool = NSAutoreleasePool::new(nil);
 
@@ -893,13 +894,7 @@
                 cursor_style: CursorStyle::Arrow,
                 cursor_visible,
                 frame_source: None,
-                renderer: renderer::new_renderer(
-                    renderer_context,
-                    native_window as *mut _,
-                    native_view as *mut _,
-                    bounds.size.map(|pixels| pixels.as_f32()),
-                    false,
-                ),
+                renderer,
                 request_frame_callback: None,
                 event_callback: None,
                 activate_callback: None,
@@ -1098,7 +1093,7 @@
 
             pool.drain();
 
-            window
+            Ok(window)
         }
     }
 
@@ -1178,6 +1173,10 @@
         }
         this.input_handler.take();
-        this.foreground_executor
+        let accesskit_adapter = this.accesskit_adapter.take();
+        let foreground_executor = this.foreground_executor.clone();
+        drop(this);
+        foreground_executor
             .spawn(async move {
+                drop(accesskit_adapter);
                 unsafe {
                     if let Some(parent) = sheet_parent {
@@ -3132,7 +3131,8 @@
                 let hit: BOOL = msg_send![description, containsString: blur_test];
                 if hit == YES {
                     let radius: id = msg_send![class!(NSNumber), numberWithDouble: 60.0f64];
-                    let _: () = msg_send![filter, setValue: radius forKey: ns_string("inputRadius")];
+                    let _: () =
+                        msg_send![filter, setValue: radius forKey: ns_string("inputRadius")];
                     let _: () = msg_send![layer, setFilters: filters];
                     break;
                 }
diff --git a/crates/gpui_platform/src/gpui_platform.rs b/crates/gpui_platform/src/gpui_platform.rs
index 1d2fea90b477..c2e070e721fe 100644
--- a/crates/gpui_platform/src/gpui_platform.rs
+++ b/crates/gpui_platform/src/gpui_platform.rs
@@ -64,9 +64,13 @@
 pub fn current_headless_renderer() -> Option<Box<dyn gpui::PlatformHeadlessRenderer>> {
     #[cfg(target_os = "macos")]
     {
-        Some(Box::new(
-            gpui_macos::metal_renderer::MetalHeadlessRenderer::new(),
-        ))
+        match gpui_macos::metal_renderer::MetalHeadlessRenderer::new() {
+            Ok(renderer) => Some(Box::new(renderer)),
+            Err(error) => {
+                eprintln!("failed to initialize headless Metal renderer: {error:#}");
+                None
+            }
+        }
     }
 
     #[cfg(not(target_os = "macos"))]
diff --git a/crates/gpui_wgpu/src/wgpu_renderer.rs b/crates/gpui_wgpu/src/wgpu_renderer.rs
index 587315debfa8..e58084906c1f 100644
--- a/crates/gpui_wgpu/src/wgpu_renderer.rs
+++ b/crates/gpui_wgpu/src/wgpu_renderer.rs
@@ -108,7 +108,7 @@
 struct WgpuResources {
     device: Arc<wgpu::Device>,
     queue: Arc<wgpu::Queue>,
-    surface: wgpu::Surface<'static>,
+    surface: Option<wgpu::Surface<'static>>,
     pipelines: WgpuPipelines,
     bind_group_layouts: WgpuBindGroupLayouts,
     atlas_sampler: wgpu::Sampler,
@@ -449,7 +449,7 @@
         let resources = WgpuResources {
             device,
             queue,
-            surface,
+            surface: Some(surface),
             pipelines,
             bind_group_layouts,
             atlas_sampler,
@@ -982,9 +982,9 @@
                 texture.destroy();
             }
 
-            resources
-                .surface
-                .configure(&resources.device, &surface_config);
+            if let Some(surface) = &resources.surface {
+                surface.configure(&resources.device, &surface_config);
+            }
 
             // Invalidate intermediate textures - they will be lazily recreated
             // in draw() after we confirm the surface is healthy. This avoids
@@ -1040,9 +1040,9 @@
             let Some(resources) = self.resources.as_mut() else {
                 return;
             };
-            resources
-                .surface
-                .configure(&resources.device, &surface_config);
+            if let Some(surface) = &resources.surface {
+                surface.configure(&resources.device, &surface_config);
+            }
             resources.pipelines = Self::create_pipelines(
                 &resources.device,
                 &resources.bind_group_layouts,
@@ -1118,24 +1118,30 @@
 
         self.atlas.before_frame();
 
-        let frame = match self.resources().surface.get_current_texture() {
+        let frame = match self
+            .resources()
+            .surface
+            .as_ref()
+            .expect("Configured surface missing")
+            .get_current_texture()
+        {
             wgpu::CurrentSurfaceTexture::Success(frame) => frame,
             wgpu::CurrentSurfaceTexture::Suboptimal(frame) => {
                 // Textures must be destroyed before the surface can be reconfigured.
                 drop(frame);
                 let surface_config = self.surface_config.clone();
                 let resources = self.resources_mut();
-                resources
-                    .surface
-                    .configure(&resources.device, &surface_config);
+                if let Some(surface) = &resources.surface {
+                    surface.configure(&resources.device, &surface_config);
+                }
                 return false;
             }
             wgpu::CurrentSurfaceTexture::Lost | wgpu::CurrentSurfaceTexture::Outdated => {
                 let surface_config = self.surface_config.clone();
                 let resources = self.resources_mut();
-                resources
-                    .surface
-                    .configure(&resources.device, &surface_config);
+                if let Some(surface) = &resources.surface {
+                    surface.configure(&resources.device, &surface_config);
+                }
                 return false;
             }
             wgpu::CurrentSurfaceTexture::Timeout | wgpu::CurrentSurfaceTexture::Occluded => {
@@ -1687,6 +1693,15 @@
         })
     }
 
+    /// Dropping the returned surface retires WSI presentation without discarding the atlas.
+    #[cfg(not(target_family = "wasm"))]
+    pub fn take_surface_for_visibility(&mut self) -> Option<wgpu::Surface<'static>> {
+        self.surface_configured = false;
+        self.resources
+            .as_mut()
+            .and_then(|resources| resources.surface.take())
+    }
+
     /// Mark the surface as unconfigured so rendering is skipped until a new
     /// surface is provided via [`replace_surface`](Self::replace_surface).
     ///
@@ -1745,7 +1760,7 @@
                 .as_mut()
                 .expect("GPU resources not available");
             surface.configure(&res.device, &self.surface_config);
-            res.surface = surface;
+            res.surface = Some(surface);
 
             // Invalidate intermediate textures — they'll be recreated lazily.
             res.invalidate_intermediate_textures();