Merge pull request #982 from storytold/fix/964-first-frame-watch

#964: start again when the first frame never reaches the screen

ROADMAP.md

@@ -4,7 +4,7 @@ VectorCraft is a clean-room, open-source, pure-Rust reimplementation of the Adob
 
 This file tracks **how far we are and what's left**. Time estimates are wall-clock hours of continuous Claude Opus 5.5 agent work (including builds and the CI gate), given both for **one agent** and for **4–6 parallel agents** on disjoint crates. They are counted from the remaining work (see [Parity estimate](#parity-estimate)), calibrated against measured throughput, and updated as work lands.
 
-_Last updated: 2026-10-10 (after placed documents (File › Place of a `.vectorcraft` file, linked), M4.14–M4.98, M8.1–M8.20, M14.4–M14.7, the MCP prompts, resource templates, completions and logging, the 2026-10-07 issue fixes, the Layers panel rework and the 2026-10-08 community contributions: Pen and shape-tool modifiers, path editing, Layers, Artboards, Swatches/Brushes and dialogs, Japanese composition and PDF text, Hebrew/Arabic type, interface languages (Spanish among them), the font menu, saved selections, MCP and EPS, the missing-font export warning (#319), open paths in the Shape Builder (#374), PDF/`.ai` import keeping strokes live and hidden and nested layers (#372), per-corner Live Corners (#381), SVG type opening at the size it draws at (#396), the Wayland clipboard with copied-file paste (#398), ruler guides that can be selected, moved and deleted (#414), two batches of Preferences options that were stored but unused (#394), skeleton reads with `document.find` for large documents over MCP (#416) and anchors dragged with Direct Selection snapping to points, segments and smart guides, clipped SVG layers opening as clipping layers (#420), PDF/`.ai` layers read on pages of tens of millions of operators (#419), Document Color Mode putting RGB greys on the black plate on request and converting pattern tiles (#421) and movable dialogs with Offset Path's Joins dropdown (#423) and numeric fields scrubbed by dragging their label (#400), stroke weight presets in the stroke unit (#426), the Appearance panel's Opacity popup (#430), type on a path brackets, flip and Type on a Path Options that keep the type in place (#429), Layers rows dragged with a ghost and dropped on the trash or New Layer (#435), tool flyouts opening on a right or corner press (#436), tool flyouts torn off into floating toolbars (#437), the Shape Builder's erase mode deleting edges too (#439), installed fonts registered outside the font folders and fonts installed while the app runs listed in the font menus (#443), alike circular corners on rectangles that aren't square (#442), tool cursors as OS cursors so the pointer no longer trails over the canvas (#444), artboards copied and pasted with their art (#446), guides dragged out of the rulers snapping to the art's side midpoints and the artboards, artboard guides (#451), the toolbar's double arrow and Window › Toolbars › Double Column switching between one and two columns in any window height (#455), the Smart Guides display options and Snapping Tolerance (#394), Font Size and Leading combo boxes with preset lists in the Character and Properties panels and the Control bar (#458), screenshots pasted from the clipboard on macOS, Windows and the web (#457), the Properties panel's Fill and Stroke matching the Control bar's, Illustrator's Window menu panel keys (Shift+F7 for Align…) and Alt-wheel zoom whatever the wheel preference (Discord feedback), the point/area type widget (Discord feedback), groups in legacy Illustrator .ai files (Discord feedback), a rotating desktop log file (#465), image controls in the Control bar and Properties panel: Image Trace with its presets, Mask, Crop Image, Embed/Unembed, and an Image Trace object's preset, Expand and Release (Discord feedback), the Pen working as the Anchor Point tool with Alt held over a selected path's handles and anchors, and anchor buttons that convert, connect and cut paths at the selected anchors (Discord feedback), Japanese hanging punctuation (burasagari, #463), Escape leaving Presentation Mode with no screen mode saved across restarts, documents dropped on the desktop app opening as tabs of their own and a note that an `.ai` file's art off its artboards isn't in the part read (#472), Add/Delete Anchor Point tool icons drawn from the Pen tool's (#479), EPS import running more of PostScript Level 3 (patterns, Type 3 fonts, mesh shadings, masked images, VM and resource probes), and a preview that stands in saying why (Discord feedback, #466, #469, #474), chords with modifiers recorded in Edit › Keyboard Shortcuts (#487), Type Object Selection by Path Only (#394), Anti-aliased Artwork (#394), Show Pixel Grid (#394), pen and touch taps pressed and lifted within one frame clicking where they tapped and the Linux/Wayland pen-tablet workaround (#491), bounding-box resizes landing on the other objects' anchors and centres with labels, and the Rotate, Scale, Shear and Reflect tools snapping their drags (#482), Shift-drag marquees that toggle the objects or anchors they reach and a Lasso whose Alt subtraction keeps the rest of the selection (#483), the mouse wheel stepping the focused numeric field, the dialogs' and preferences' drag values made such fields (#485), Show The Home Screen When No Documents Are Open (#394), Numbers Without Units Are Points (#394), Auto-Collapse Iconic Panels (#394), the Contextual Task Bar moved by its handle and its More Options menu pinning and resetting its position, a designed macOS DMG windoLine truncated
+_Last updated: 2026-10-10 (after placed documents (File › Place of a `.vectorcraft` file, linked), M4.14–M4.98, M8.1–M8.20, M14.4–M14.7, the MCP prompts, resource templates, completions and logging, the 2026-10-07 issue fixes, the Layers panel rework and the 2026-10-08 community contributions: Pen and shape-tool modifiers, path editing, Layers, Artboards, Swatches/Brushes and dialogs, Japanese composition and PDF text, Hebrew/Arabic type, interface languages (Spanish among them), the font menu, saved selections, MCP and EPS, the missing-font export warning (#319), open paths in the Shape Builder (#374), PDF/`.ai` import keeping strokes live and hidden and nested layers (#372), per-corner Live Corners (#381), SVG type opening at the size it draws at (#396), the Wayland clipboard with copied-file paste (#398), ruler guides that can be selected, moved and deleted (#414), two batches of Preferences options that were stored but unused (#394), skeleton reads with `document.find` for large documents over MCP (#416) and anchors dragged with Direct Selection snapping to points, segments and smart guides, clipped SVG layers opening as clipping layers (#420), PDF/`.ai` layers read on pages of tens of millions of operators (#419), Document Color Mode putting RGB greys on the black plate on request and converting pattern tiles (#421) and movable dialogs with Offset Path's Joins dropdown (#423) and numeric fields scrubbed by dragging their label (#400), stroke weight presets in the stroke unit (#426), the Appearance panel's Opacity popup (#430), type on a path brackets, flip and Type on a Path Options that keep the type in place (#429), Layers rows dragged with a ghost and dropped on the trash or New Layer (#435), tool flyouts opening on a right or corner press (#436), tool flyouts torn off into floating toolbars (#437), the Shape Builder's erase mode deleting edges too (#439), installed fonts registered outside the font folders and fonts installed while the app runs listed in the font menus (#443), alike circular corners on rectangles that aren't square (#442), tool cursors as OS cursors so the pointer no longer trails over the canvas (#444), artboards copied and pasted with their art (#446), guides dragged out of the rulers snapping to the art's side midpoints and the artboards, artboard guides (#451), the toolbar's double arrow and Window › Toolbars › Double Column switching between one and two columns in any window height (#455), the Smart Guides display options and Snapping Tolerance (#394), Font Size and Leading combo boxes with preset lists in the Character and Properties panels and the Control bar (#458), screenshots pasted from the clipboard on macOS, Windows and the web (#457), the Properties panel's Fill and Stroke matching the Control bar's, Illustrator's Window menu panel keys (Shift+F7 for Align…) and Alt-wheel zoom whatever the wheel preference (Discord feedback), the point/area type widget (Discord feedback), groups in legacy Illustrator .ai files (Discord feedback), a rotating desktop log file (#465), image controls in the Control bar and Properties panel: Image Trace with its presets, Mask, Crop Image, Embed/Unembed, and an Image Trace object's preset, Expand and Release (Discord feedback), the Pen working as the Anchor Point tool with Alt held over a selected path's handles and anchors, and anchor buttons that convert, connect and cut paths at the selected anchors (Discord feedback), Japanese hanging punctuation (burasagari, #463), Escape leaving Presentation Mode with no screen mode saved across restarts, documents dropped on the desktop app opening as tabs of their own and a note that an `.ai` file's art off its artboards isn't in the part read (#472), Add/Delete Anchor Point tool icons drawn from the Pen tool's (#479), EPS import running more of PostScript Level 3 (patterns, Type 3 fonts, mesh shadings, masked images, VM and resource probes), and a preview that stands in saying why (Discord feedback, #466, #469, #474), chords with modifiers recorded in Edit › Keyboard Shortcuts (#487), Type Object Selection by Path Only (#394), Anti-aliased Artwork (#394), Show Pixel Grid (#394), pen and touch taps pressed and lifted within one frame clicking where they tapped and the Linux/Wayland pen-tablet workaround (#491), bounding-box resizes landing on the other objects' anchors and centres with labels, and the Rotate, Scale, Shear and Reflect tools snapping their drags (#482), Shift-drag marquees that toggle the objects or anchors they reach and a Lasso whose Alt subtraction keeps the rest of the selection (#483), the mouse wheel stepping the focused numeric field, the dialogs' and preferences' drag values made such fields (#485), Show The Home Screen When No Documents Are Open (#394), Numbers Without Units Are Points (#394), Auto-Collapse Iconic Panels (#394), the Contextual Task Bar moved by its handle and its More Options menu pinning and resetting its position, a designed macOS DMG windoLine truncated
 
 ## Where we are
 

apps/vectorcraft/src/gpu.rs

@@ -26,9 +26,16 @@
 //! the graphics fail while the window is starting up, [`finish`] starts the app again without
 //! that adapter, as the next one in the order would be tried. Each restart leaves out one more
 //! adapter, so it ends when none is left.
+//!
+//! An adapter can also hang instead of failing: on a hybrid laptop with High Performance chosen,
+//! the discrete GPU never put the window's first frame on the screen, with no error and no panic,
+//! and the app stayed in the background without a window (#964). [`watch_first_frame`] gives the
+//! first frame [`FIRST_FRAME_TIMEOUT`] once the app is created and, when it doesn't come, starts
+//! the app again without that adapter in the same way.
 
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, OnceLock};
+use std::time::{Duration, Instant};
 
 use eframe::egui_wgpu::NativeAdapterSelectorMethod;
 use eframe::wgpu::{self, Backend, Backends, DeviceType, PowerPreference};
@@ -50,6 +57,11 @@ const HELP: &str =
 /// window is something else (such as the compositor restarting).
 pub const STARTUP_FRAMES: u64 = 10;
 
+/// How long the window's first frame may take to reach the screen, from the app's creation,
+/// before its adapter counts as hanging ([`watch_first_frame`]). The first frame draws the whole
+/// interface and compiles its shaders, a second at most on a slow machine.
+pub const FIRST_FRAME_TIMEOUT: Duration = Duration::from_secs(20);
+
 /// The preference used when Preferences say Automatic. Windows and macOS show frames from any GPU
 /// (the integrated one avoids the flicker of #306). Elsewhere, the system's own order: Mesa's
 /// device-select layer puts the GPU the desktop runs on first (the integrated one on hybrid
@@ -311,6 +323,8 @@ pub struct Startup {
     adapter: OnceLock<String>,
     /// The UI's context, which counts the frames run.
     ui: OnceLock<egui::Context>,
+    /// When the app was created, the files named at the start opened: the first frame is due.
+    ready: OnceLock<Instant>,
 }
 
 impl Startup {
@@ -319,6 +333,71 @@ impl Startup {
         // Set once; the window is created once.
         let _ = self.ui.set(ctx.clone());
     }
+
+    /// The app is ready to draw its first frame.
+    pub fn ready(&self) {
+        // Set once, like `created`.
+        let _ = self.ready.set(Instant::now());
+    }
+}
+
+/// What [`watch_first_frame`] makes of the window's start.
+#[derive(Debug, PartialEq, Eq)]
+enum FirstFrame {
+    /// Not due yet.
+    Wait,
+    /// On the screen (the second frame began, so the first was presented), or the window was
+    /// minimized at the start: nothing to watch.
+    Shown,
+    /// Overdue.
+    Hung,
+}
+
+/// The window's start after `frames` frames run, `since` its first frame was due.
+fn first_frame(frames: u64, since: Duration, minimized: bool) -> FirstFrame {
+    if frames >= 2 || minimized {
+        FirstFrame::Shown
+    } else if since >= FIRST_FRAME_TIMEOUT {
+        FirstFrame::Hung
+    } else {
+        FirstFrame::Wait
+    }
+}
+
+/// Watch the window's first frame from another thread: when it hasn't reached the screen
+/// [`FIRST_FRAME_TIMEOUT`] after the app was created ([`Startup::ready`]), start the app again
+/// without the adapter, as [`finish`] does for one that failed, and end this process, whose UI
+/// thread is stuck in the graphics driver.
+pub fn watch_first_frame(startup: Arc<Startup>) {
+    let watch = move || loop {
+        std::thread::sleep(Duration::from_millis(250));
+        let Some(due) = startup.ready.get() else { continue };
+        let ui = startup.ui.get();
+        let frames = ui.map_or(0, egui::Context::cumulative_frame_nr);
+        let minimized = ui.and_then(|c| c.input(|i| i.viewport().minimized)).unwrap_or(false);
+        match first_frame(frames, due.elapsed(), minimized) {
+            FirstFrame::Wait => continue,
+            FirstFrame::Shown => return,
+            FirstFrame::Hung => {}
+        }
+        let mut skip = skipped();
+        let Some(failed) = restart_without(true, frames, startup.adapter.get().map(String::as_str), &skip) else { return };
+        log::error!(
+            "the window's first frame didn't reach the screen in {}s on graphics adapter {failed}: starting again without it",
+            FIRST_FRAME_TIMEOUT.as_secs()
+        );
+        skip.push(failed.to_string());
+        match restart(&skip.join(",")) {
+            Ok(()) => std::process::exit(0),
+            Err(e) => {
+                log::error!("starting again failed: {e}");
+                return;
+            }
+        }
+    };
+    if let Err(e) = std::thread::Builder::new().name("first frame".into()).spawn(watch) {
+        log::warn!("no watch on the window's first frame: {e}");
+    }
 }
 
 /// eframe's adapter choice: the first of [`adapter_order`] for `power`, the GPUs that drive a
@@ -729,6 +808,24 @@ mod tests {
         assert_eq!(parse_skip(&key(Backend::Gl, 0, 0, "Mesa, llvmpipe")), ["Gl:Mesa  llvmpipe"]);
     }
 
+    #[test]
+    fn a_first_frame_that_never_reaches_the_screen_hangs_its_adapter() {
+        let s = Duration::from_secs;
+        // The second frame began: the first was presented.
+        assert_eq!(first_frame(2, s(60), false), FirstFrame::Shown);
+        // Still drawing (or presenting) the first frame: waited for, then given up on (#964).
+        for frames in [0, 1] {
+            assert_eq!(first_frame(frames, s(3), false), FirstFrame::Wait);
+            assert_eq!(first_frame(frames, FIRST_FRAME_TIMEOUT, false), FirstFrame::Hung);
+        }
+        // A window minimized at the start may not draw again until restored.
+        assert_eq!(first_frame(1, s(60), true), FirstFrame::Shown);
+        // A hung adapter is left out once, like one that failed.
+        let skip = vec!["Dx12:10de:28a0".to_string()];
+        assert_eq!(restart_without(true, 1, Some("Dx12:10de:28a0"), &skip), None);
+        assert_eq!(restart_without(true, 1, Some("Dx12:8086:a7a8"), &skip), Some("Dx12:8086:a7a8"));
+    }
+
     #[test]
     fn a_restart_tries_the_next_adapter() {
         let c = issue_502();

apps/vectorcraft/src/main.rs

@@ -504,7 +504,9 @@ fn main() -> std::process::ExitCode {
     #[cfg(feature = "wgpu")]
     let displays = gpu::preferred_displays(gpu_pref, power_env);
     #[cfg(feature = "wgpu")]
-    if gpu::automatic(gpu_pref, power_env) {
+    let chosen_gpu = !gpu::automatic(gpu_pref, power_env);
+    #[cfg(feature = "wgpu")]
+    if !chosen_gpu {
         let listed: Vec<String> = displays.iter().map(ToString::to_string).collect();
         log::info!("display GPUs (PCI vendor:device): {}", if listed.is_empty() { "unknown".to_string() } else { listed.join(", ") });
     } else {
@@ -534,6 +536,8 @@ fn main() -> std::process::ExitCode {
     };
     #[cfg(feature = "wgpu")]
     gpu::watch_panics();
+    #[cfg(feature = "wgpu")]
+    gpu::watch_first_frame(startup.clone());
     // Files opened from Finder and the Dock arrive as events, not arguments.
     #[cfg(target_os = "macos")]
     open_documents::install();
@@ -577,7 +581,15 @@ fn main() -> std::process::ExitCode {
                     log::info!("rendering with {summary} (power preference {power:?})");
                     created.created(&cc.egui_ctx);
                     if !gpu::skipped().is_empty() {
-                        app.status(format!("The graphics processor tried first couldn't show the window, so VectorCraft started again on {summary}"));
+                        // A processor chosen in Settings can be the one that can't show the window.
+                        let hint = if chosen_gpu {
+                            " (Settings › Performance › Graphics Processor › Automatic uses the one that drives your display)"
+                        } else {
+                            ""
+                        };
+                        app.status(format!(
+                            "The graphics processor tried first couldn't show the window, so VectorCraft started again on {summary}{hint}"
+                        ));
                     }
                     app.graphics_adapter = Some(summary);
                     let (loss, ctx) = (graphics_loss.clone(), cc.egui_ctx.clone());
@@ -609,6 +621,9 @@ fn main() -> std::process::ExitCode {
                 #[cfg(not(target_os = "macos"))]
                 let _ = in_window_menus;
                 file_access::unconfined(|| open_files(&mut app, files));
+                // The first frame is due from now (`gpu::watch_first_frame`).
+                #[cfg(feature = "wgpu")]
+                created.ready();
                 Ok(Box::new(App { app, graphics_loss, graphics_lost: false, frames: 0 }))
             }),
         )

docs/development.md

@@ -57,6 +57,8 @@ The canvas is rasterized on the CPU (`vectorcraft-render`, vello_cpu); the GPU (
   - **Automatic on Linux and the BSDs** is the GPU that drives the panel or a monitor, then the system's order: Mesa's Vulkan device-select layer puts the GPU the desktop runs on first (the integrated one on hybrid laptops; `DRI_PRIME` and `MESA_VK_DEVICE_SELECT` steer it). A Wayland compositor may not accept frames from another GPU: on a desktop whose compositor ran on an NVIDIA GPU, rendering on the Ryzen's integrated GPU made KWin end the window's connection ("importing the supplied dmabufs failed") and 0.5.0 crashed at startup (#502).
   - 0.5.0 saved `powerSaving`, its default, for everyone; it reads as `automatic`.
 - **If the window fails on its adapter while starting up** (an error from wgpu, or a panic inside wgpu or egui-wgpu during the first frames), the app starts again without that adapter and tries the next one, telling which in the status bar; the run that failed keeps its log as `vectorcraft.1.log`. On Unix the new app replaces the process (an AppImage stays mounted); on Windows it starts beside it. Adapters are told apart by backend and PCI ids, or by name where the backend reports no ids (Metal lists every GPU of a dual-GPU Mac as `0000:0000`, #651). The adapters left out travel in `VECTORCRAFT_GPU_SKIP` (`backend:vendor:device`, such as `Vulkan:1002:164e`), one more on each restart, so the restarts end. When no adapter is left, the app logs why and exits with an error instead of panicking.
+- **If the window's first frame never reaches the screen** within 20 seconds of the app being created (the files named at the start opened), the adapter counts as hanging and the app starts again without it in the same way (#964: High Performance on a hybrid laptop left the app running in the background with no window and nothing in the log). A window minimized at the start isn't counted. When the processor that hung was chosen in Preferences, the status bar points to Automatic.
+- **To recover from a Graphics Processor choice that doesn't work** without editing files: start once with `WGPU_POWER_PREF=low` (or `WGPU_ADAPTER_NAME=…`), which overrides the preference for that start while settings still save, and set Graphics Processor back to Automatic. `VECTORCRAFT_NO_PREFS=1` also starts without it, but saves nothing.
 - **Environment variables** for when the choice still goes wrong, all read at startup and stronger than the preference:
   - `WGPU_POWER_PREF`: `low`, `high` or `none` (the system's order).
   - `WGPU_ADAPTER_NAME`: part of an adapter's name, any case (`WGPU_ADAPTER_NAME=nvidia`, `=radv`, `=intel`); the names are in the log.