From f13b6fc0ef72155a6044271f0dce2ba808e547b5 Mon Sep 17 00:00:00 2001
From: Nils Pukropp <nils@narl.io>
Date: Mon, 28 Sep 2026 23:35:14 +0200
Subject: [PATCH] feat(gui): add pdfs-prompt --preload for session autostart

--preload registers the resident GTK launcher and realizes its window
without showing it, so the first shortcut opens it as fast as later
ones. When a launcher is already running it exits without activating
it.

The application hold now happens in startup, which only the primary
instance runs. Taken before registration, it also kept every remote
invocation alive after it had forwarded its activation.
---
 crates/pdfs-gui/src/hud/mod.rs |  6 ++++
 crates/pdfs-gui/src/prompt.rs  | 56 ++++++++++++++++++++++++++++++++--
 docs/USER_GUIDE.md             |  9 ++++++
 3 files changed, 69 insertions(+), 2 deletions(-)

diff --git a/crates/pdfs-gui/src/hud/mod.rs b/crates/pdfs-gui/src/hud/mod.rs
index a8f0963..c282a39 100644
--- a/crates/pdfs-gui/src/hud/mod.rs
+++ b/crates/pdfs-gui/src/hud/mod.rs
@@ -535,6 +535,12 @@ async fn mounted_target_within(mountpoint: PathBuf, hit: SearchHit) -> Option<Pa
 }
 
 impl Ui {
+    /// `--preload`: create the surface, renderer and style state now, without
+    /// mapping the window, so the first real summon only has to present it.
+    pub(crate) fn preload(&self) {
+        WidgetExt::realize(&self.window);
+    }
+
     /// Reset and present the resident prompt in response to GApplication
     /// activation. A second invocation while a file is materialising merely
     /// raises the progress window; it must not make the in-flight open mutable.
diff --git a/crates/pdfs-gui/src/prompt.rs b/crates/pdfs-gui/src/prompt.rs
index 3cb8e8e..6da0c04 100644
--- a/crates/pdfs-gui/src/prompt.rs
+++ b/crates/pdfs-gui/src/prompt.rs
@@ -268,6 +268,9 @@ Options:
                         every keystroke — results appear as you type, unlike
                         --dmenu. Also settable as \"prompt\": { \"mode\": \"fzf\" }.
   --gtk                 Force the built-in window, overriding that setting.
+  --preload             Start the built-in window hidden and stay resident, so
+                        the first summon opens at once. For session autostart;
+                        does nothing if the prompt is already running.
   --menu <COMMAND>      Launcher command line for --dmenu, e.g.
                         --menu 'fuzzel --dmenu --width 60'. Overrides
                         \"prompt\": { \"menu\": [...] }.
@@ -293,6 +296,8 @@ struct Args {
     feed: Option<Option<String>>,
     /// `--inner`: we are the process a spawned terminal is running.
     inner: bool,
+    /// `--preload`: become the resident GTK instance without showing it.
+    preload: bool,
 }
 
 fn parse_args(argv: impl Iterator<Item = String>) -> Result<Args, String> {
@@ -302,6 +307,7 @@ fn parse_args(argv: impl Iterator<Item = String>) -> Result<Args, String> {
         query: None,
         feed: None,
         inner: false,
+        preload: false,
     };
     let mut argv = argv.peekable();
     while let Some(arg) = argv.next() {
@@ -310,6 +316,7 @@ fn parse_args(argv: impl Iterator<Item = String>) -> Result<Args, String> {
             "--fzf" => args.mode = Some(PromptMode::Fzf),
             "--gtk" => args.mode = Some(PromptMode::Gtk),
             "--inner" => args.inner = true,
+            "--preload" => args.preload = true,
             // fzf passes an empty argument for an empty input, so a missing
             // value here is that case rather than a user error.
             "--feed" => args.feed = Some(argv.next().filter(|text| !text.trim().is_empty())),
@@ -337,6 +344,13 @@ fn parse_args(argv: impl Iterator<Item = String>) -> Result<Args, String> {
             other => return Err(format!("unrecognised argument: {other}")),
         }
     }
+    // Only the GTK window has a resident process worth warming up.
+    if args.preload {
+        if matches!(args.mode, Some(PromptMode::Dmenu | PromptMode::Fzf)) || args.query.is_some() {
+            return Err("--preload only applies to the built-in window".to_string());
+        }
+        args.mode = Some(PromptMode::Gtk);
+    }
     Ok(args)
 }
 
@@ -398,9 +412,31 @@ fn main() -> glib::ExitCode {
     // GtkApplication normally remains active while it owns a window, including
     // when that window is hidden. Hold it explicitly as well: residency is a
     // product requirement here, not an incidental window-lifetime side effect.
-    let _resident = app.hold();
-    app.connect_startup(|_| theme::load_resources("/de/nils/protondrivelinux/prompt.css"));
+    // Only the primary instance runs startup; a hold taken before registration
+    // would also keep every remote invocation alive after it has forwarded
+    // its activation.
+    let resident = Rc::new(RefCell::new(None));
+    app.connect_startup(move |app| {
+        *resident.borrow_mut() = Some(app.hold());
+        theme::load_resources("/de/nils/protondrivelinux/prompt.css");
+    });
+    if args.preload {
+        if let Err(e) = app.register(gtk4::gio::Cancellable::NONE) {
+            eprintln!("pdfs-prompt: {e}");
+            return glib::ExitCode::FAILURE;
+        }
+        // Another instance is already resident; activating it would show it.
+        // Dropping a registered application that never ran makes GIO warn
+        // about the D-Bus registration, so leave it to process exit.
+        if app.is_remote() {
+            std::mem::forget(app);
+            return glib::ExitCode::SUCCESS;
+        }
+    }
     let prompt: Rc<RefCell<Option<Rc<hud::Ui>>>> = Rc::new(RefCell::new(None));
+    // The first activation of a preloading instance is its own startup, not a
+    // summon: build the window but leave it hidden.
+    let quiet = std::cell::Cell::new(args.preload);
     app.connect_activate(move |app| {
         let ui = if let Some(ui) = prompt.borrow().clone() {
             ui
@@ -411,6 +447,10 @@ fn main() -> glib::ExitCode {
             *prompt.borrow_mut() = Some(ui.clone());
             ui
         };
+        if quiet.replace(false) {
+            ui.preload();
+            return;
+        }
         ui.activate();
     });
     // GTK must not try to parse our own flags; they were consumed above.
@@ -582,4 +622,16 @@ mod tests {
         let args = parse(&["--dmenu", "--query", "tax return 2024"]).unwrap();
         assert_eq!(args.query.as_deref(), Some("tax return 2024"));
     }
+
+    #[test]
+    fn preload_forces_the_gtk_window_and_rejects_the_launchers() {
+        let args = parse(&["--preload"]).unwrap();
+        assert!(args.preload);
+        assert_eq!(args.mode, Some(PromptMode::Gtk));
+
+        assert!(parse(&["--preload", "--dmenu"]).is_err());
+        assert!(parse(&["--fzf", "--preload"]).is_err());
+        assert!(parse(&["--preload", "--menu", "fuzzel --dmenu"]).is_err());
+        assert!(parse(&["--preload", "--query", "tax"]).is_err());
+    }
 }
diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md
index 9f9f9d5..60832c7 100644
--- a/docs/USER_GUIDE.md
+++ b/docs/USER_GUIDE.md
@@ -235,6 +235,15 @@ The window stays loaded after the first use, so later shortcuts open it instantl
 and video open straight from the Proton Drive folder, so players can start before the whole file
 downloads. Other Drive files download first, then open.
 
+To make the first shortcut instant as well, start the launcher hidden with your session.
+`pdfs-prompt --preload` loads the window without showing it and does nothing if the launcher is
+already running. For Hyprland:
+
+```ini
+exec-once = pdfs-prompt --preload
+bind = SUPER, space, exec, pdfs-prompt
+```
+
 ### Using your own launcher
 
 `pdfs-prompt --dmenu` shows the results in fuzzel, rofi, wofi, tofi, bemenu or dmenu, whichever is