Try every GPU, not only the fastest one

`request_adapter` with `HighPerformance` returns one adapter and no
second chance. That is right on a healthy machine and wrong on one with
a sick GPU, which is not rare: observed 2026-08-29 on a laptop whose
discrete card had hit an NVRM assertion failure and a fullchip reset.
The driver still advertised it, wgpu dutifully picked it as the highest
performing, and the process died on it — while a working integrated GPU
and a working external card sat unused in the same enumeration. A photo
editor that will not start because the *fastest* GPU is broken, on a
machine holding two that are not, is worse than a slow one.

So: enumerate, order by preference, take the first that yields a device.
The ordering reproduces what `HighPerformance` meant, so a healthy
machine picks what it always picked and pays one enumeration for it. A
CPU adapter sorts last rather than being excluded — software rendering
is a poor experience and a working one.

Which GPU to prefer is now a policy rather than an assumption, because
the fastest is not obviously the right one. A 24 MP frame is ~96 MB of
RGBA and every upload and export readback crosses PCIe on a discrete
card, where an integrated GPU shares memory and crosses nothing — and
does not empty a battery.

Measured before choosing a default, on this machine's Iris Xe against
its RX 5700 XT. The fused colour pass is within 1.5x, which is the
shape shared memory suits. The neighbourhood stage is 5-8x slower, and
that decides it: clarity at 1920x1200 costs 20 ms on the iGPU, over the
budget on its own at the smallest size tested. So `Performance` stays
the default and `Efficiency` is offered rather than chosen
(`DARKROOM_GPU=integrated`).

docs/frame-budget.md carries the table, and says what it does *not*
show: the harness renders from a resident texture and never uploads or
reads back, so the transfer cost an iGPU avoids appears in none of it.
Import, export and the thumbnail sweeps may well go the other way.

What this cannot fix: a GPU sick enough to accept `request_device` and
segfault afterwards, which arrives as a driver crash rather than an
error. It moves the boundary from "the preferred adapter is unusable" to
"unusable and dishonest about it".

core/dr-gpu/src/lib.rs

@@ -74,6 +74,68 @@ pub struct SharedGpu {
     pub adapter: wgpu::Adapter,
 }
 
+/// TRACES: FR-DSP-1 | NFR-RES-4
+/// Which GPU to prefer, on a machine with more than one.
+///
+/// **Not obviously the fastest one**, which is why this is a choice rather
+/// than a constant. A discrete card wins on raw compute and loses on every
+/// byte that has to reach it: a 24 MP frame is ~96 MB of RGBA, and each
+/// upload and each export readback crosses PCIe. An integrated GPU shares
+/// memory with the CPU, so those transfers are not transfers. It also does not
+/// empty a laptop battery.
+///
+/// Which of those dominates depends on the work — a slider drag over a
+/// resident texture is compute-bound and favours the discrete card, while
+/// import, export and thumbnailing are transfer-heavy — so the honest thing is
+/// to let it be set rather than to assume.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum AdapterPreference {
+    /// The most capable GPU. What this has always done, and the default: it is
+    /// the right answer for interactive editing, which is the frame budget
+    /// that FR-DSP-3 actually measures.
+    #[default]
+    Performance,
+    /// An integrated GPU where there is one — shared memory, no bus crossing,
+    /// and far less power.
+    Efficiency,
+}
+
+impl AdapterPreference {
+    /// Read the override, defaulting to [`Performance`](Self::Performance).
+    ///
+    /// An environment variable rather than a setting, *for now*: this belongs
+    /// on the settings page beside the cache budget, and putting it there
+    /// needs a control and a restart prompt, because the device is opened once
+    /// at startup and shared with the compositor. The variable is what makes
+    /// the choice testable and gives someone with a broken primary GPU a way
+    /// out today.
+    pub fn from_env() -> Self {
+        match std::env::var("DARKROOM_GPU").as_deref() {
+            Ok("integrated") | Ok("efficiency") | Ok("igpu") => Self::Efficiency,
+            _ => Self::Performance,
+        }
+    }
+
+    /// How much we want an adapter, lowest first.
+    ///
+    /// A CPU adapter sorts last under both policies rather than being
+    /// excluded: software rendering is a poor experience and a working one,
+    /// and on a machine where every real GPU has failed it is the difference
+    /// between a slow editor and no editor.
+    fn rank(self, device_type: wgpu::DeviceType) -> u8 {
+        use wgpu::DeviceType as D;
+        match (self, device_type) {
+            (_, D::Cpu) => 4,
+            (Self::Performance, D::DiscreteGpu) => 0,
+            (Self::Performance, D::IntegratedGpu) => 1,
+            (Self::Efficiency, D::IntegratedGpu) => 0,
+            (Self::Efficiency, D::DiscreteGpu) => 1,
+            (_, D::VirtualGpu) => 2,
+            (_, D::Other) => 3,
+        }
+    }
+}
+
 impl GpuContext {
     /// Create a headless context — no surface, no window.
     ///
@@ -111,6 +173,38 @@ impl GpuContext {
         Self::open(wgpu::Backends::VULKAN).await
     }
 
+    /// TRACES: FR-DSP-1 | NFR-R1
+    /// Open a device, trying every adapter rather than only the best one.
+    ///
+    /// # Why this is not `request_adapter`
+    ///
+    /// `request_adapter` with `HighPerformance` returns *one* adapter and no
+    /// second chance. That is the right answer on a healthy machine and the
+    /// wrong one on a machine with a sick GPU, which is not a rare state:
+    /// observed 2026-08-29 on a laptop whose discrete card had hit an NVRM
+    /// assertion failure and a fullchip reset. The driver still advertised the
+    /// adapter, `request_adapter` dutifully picked it as the highest
+    /// performing, and the process died on it — while a working integrated GPU
+    /// and a working external card sat unused in the same enumeration.
+    ///
+    /// A photo editor that will not start because the *fastest* GPU is broken,
+    /// on a machine holding two that are not, is worse than a slow one.
+    ///
+    /// So: enumerate, order by how much we want each, and take the first that
+    /// actually yields a device. The ordering reproduces what
+    /// `HighPerformance` means — discrete, then integrated, then anything —
+    /// so the healthy case picks exactly what it picked before and pays one
+    /// extra enumeration for it.
+    ///
+    /// # What this cannot do
+    ///
+    /// A GPU sick enough to accept `request_device` and fail later is still
+    /// fatal, because the failure arrives as a segfault inside the driver
+    /// rather than as an error we could catch. This moves the boundary from
+    /// "the preferred adapter is unusable" to "the preferred adapter is
+    /// unusable *and* dishonest about it"; it does not remove it. Device loss
+    /// after a successful open is a different problem with a different answer
+    /// (ARCH §5.6).
     async fn open(backends: wgpu::Backends) -> Result<SharedGpu, GpuError> {
         // `new_without_display_handle` rather than a struct literal: the
         // descriptor carries a boxed display handle and so has no `Default`,
@@ -119,27 +213,61 @@ impl GpuContext {
         descriptor.backends = backends;
         let instance = wgpu::Instance::new(descriptor);
 
-        let adapter = instance
-            .request_adapter(&wgpu::RequestAdapterOptions {
-                power_preference: wgpu::PowerPreference::HighPerformance,
-                compatible_surface: None,
-                force_fallback_adapter: false,
-            })
-            .await
-            // A `Result` since wgpu 24, where it was an `Option`. The error
-            // says which backends were tried, which is worth more than the
-            // bare "no adapter" this used to report.
-            .map_err(|_| GpuError::NoAdapter)?;
+        let mut adapters: Vec<wgpu::Adapter> = instance.enumerate_adapters(backends).await;
+        if adapters.is_empty() {
+            return Err(GpuError::NoAdapter);
+        }
+        let policy = AdapterPreference::from_env();
+        adapters.sort_by_key(|a| policy.rank(a.get_info().device_type));
 
-        let adapter_info = adapter.get_info();
-        log::info!(
-            "gpu: {} ({:?}, {:?})",
-            adapter_info.name,
-            adapter_info.device_type,
-            adapter_info.backend
-        );
+        // Kept so a total failure can say what it tried. "No suitable GPU
+        // adapter found" on a machine with three of them sends the reader to
+        // look for a driver that is installed and loaded.
+        let mut refusals: Vec<String> = Vec::new();
 
-        let (device, queue) = adapter
+        for adapter in adapters {
+            let adapter_info = adapter.get_info();
+            match Self::device_from(&adapter).await {
+                Ok((device, queue)) => {
+                    log::info!(
+                        "gpu: {} ({:?}, {:?})",
+                        adapter_info.name,
+                        adapter_info.device_type,
+                        adapter_info.backend
+                    );
+                    if !refusals.is_empty() {
+                        // At `info`, not `debug`: the user is now running on
+                        // their second-choice GPU and any performance
+                        // complaint that follows begins here.
+                        log::info!(
+                            "gpu: fell back after {} unusable adapter(s): {}",
+                            refusals.len(),
+                            refusals.join("; ")
+                        );
+                    }
+                    return Ok(SharedGpu {
+                        ctx: Self {
+                            device: Arc::new(device),
+                            queue: Arc::new(queue),
+                            adapter_info,
+                        },
+                        instance,
+                        adapter,
+                    });
+                }
+                Err(e) => refusals.push(format!("{} ({e})", adapter_info.name)),
+            }
+        }
+
+        Err(GpuError::DeviceRequest(format!(
+            "every adapter refused a device: {}",
+            refusals.join("; ")
+        )))
+    }
+
+    /// Ask one adapter for a device, with the limits the pipeline needs.
+    async fn device_from(adapter: &wgpu::Adapter) -> Result<(wgpu::Device, wgpu::Queue), GpuError> {
+        adapter
             .request_device(&wgpu::DeviceDescriptor {
                 label: Some("darkroom-device"),
                 required_features: wgpu::Features::empty(),
@@ -164,17 +292,7 @@ impl GpuContext {
                 trace: wgpu::Trace::Off,
             })
             .await
-            .map_err(|e| GpuError::DeviceRequest(e.to_string()))?;
-
-        Ok(SharedGpu {
-            ctx: Self {
-                device: Arc::new(device),
-                queue: Arc::new(queue),
-                adapter_info,
-            },
-            instance,
-            adapter,
-        })
+            .map_err(|e| GpuError::DeviceRequest(e.to_string()))
     }
 
     /// Build a context from a device and queue owned by someone else — the
@@ -597,3 +715,85 @@ mod tests {
         assert_eq!(rt.size(), (1, 1));
     }
 }
+
+#[cfg(test)]
+mod adapter_choice_tests {
+    //! Which GPU gets picked, and what happens when it will not open.
+    //!
+    //! These are about the *ordering*, which is pure — opening a device needs
+    //! hardware and is covered by every other test in this crate implicitly.
+
+    use super::*;
+
+    /// Only the two fields the ordering reads are set; the rest come from
+    /// `Default`, so a wgpu upgrade that adds another does not break this.
+    /// The order adapters would be tried in, named so a failure reads as the
+    /// hardware it stands for.
+    fn order(policy: AdapterPreference, mut gpus: Vec<(&str, wgpu::DeviceType)>) -> Vec<&str> {
+        gpus.sort_by_key(|(_, t)| policy.rank(*t));
+        gpus.into_iter().map(|(name, _)| name).collect()
+    }
+
+    fn a_laptop() -> Vec<(&'static str, wgpu::DeviceType)> {
+        vec![
+            ("Iris Xe", wgpu::DeviceType::IntegratedGpu),
+            ("RTX 3050", wgpu::DeviceType::DiscreteGpu),
+            ("llvmpipe", wgpu::DeviceType::Cpu),
+        ]
+    }
+
+    #[test]
+    fn performance_takes_the_discrete_card() {
+        // What this has always done, and what an interactive slider drag wants:
+        // the texture is already resident, so the work is compute and the bus
+        // does not come into it.
+        assert_eq!(
+            order(AdapterPreference::Performance, a_laptop()),
+            ["RTX 3050", "Iris Xe", "llvmpipe"]
+        );
+    }
+
+    #[test]
+    fn efficiency_takes_the_integrated_one() {
+        // Shared memory, so a 96 MB frame upload is not a transfer, and a
+        // laptop battery that lasts. The discrete card stays as the fallback
+        // rather than being excluded.
+        assert_eq!(
+            order(AdapterPreference::Efficiency, a_laptop()),
+            ["Iris Xe", "RTX 3050", "llvmpipe"]
+        );
+    }
+
+    #[test]
+    fn software_rendering_is_last_but_never_dropped() {
+        // On a machine where every real GPU has failed this is the difference
+        // between a slow editor and no editor.
+        for policy in [
+            AdapterPreference::Performance,
+            AdapterPreference::Efficiency,
+        ] {
+            assert_eq!(
+                *order(policy, a_laptop()).last().unwrap(),
+                "llvmpipe",
+                "{policy:?}"
+            );
+        }
+    }
+
+    #[test]
+    fn a_machine_with_one_gpu_is_unaffected_by_the_policy() {
+        // The common case: no choice to make, and no behaviour to change.
+        let one = vec![("Iris Xe", wgpu::DeviceType::IntegratedGpu)];
+        assert_eq!(
+            order(AdapterPreference::Performance, one.clone()),
+            order(AdapterPreference::Efficiency, one)
+        );
+    }
+
+    #[test]
+    fn the_default_is_what_it_did_before() {
+        // Changing which GPU an existing user lands on is not something to do
+        // by accident.
+        assert_eq!(AdapterPreference::default(), AdapterPreference::Performance);
+    }
+}