M3: look up named destinations off the UI thread, and open at the latest place asked for (storytold#3425)

A named-destination lookup reads the page tree and the whole name tree:
about 100 ms for a 3,000-page manual with 30,000 names. In the running
app it now runs on its own thread, and the tab moves when the frame loop
picks up the answer. Startup and inline test runs still resolve it in
place, as opening does. A newer destination for the same document drops
a lookup still in flight.

A second launch that asks for another place while the file is still
opening now replaces the pending open's destination, instead of being
dropped.

Raised by CodeRabbit in review of storytold#5049.

Author: hazeliscoding

ROADMAP.md

@@ -200,7 +200,7 @@ Ranked; detail and the full milestone table in [docs/roadmap.md](docs/roadmap.md
 
 ## Progress log
 
-- **2026-10-27 (M3, #3425):** A file named with open parameters, as help systems start a PDF reader (`manual.pdf#nameddest=Intro`, `#page=12` or `#Intro`), opens at that destination instead of failing to read `manual.pdf#…`: at launch, when another launch hands it over, and in its tab when it is already open. Other parameters are ignored. The app now also applies a GoToR link's named destination, looked up in the target's /Names /Dests or catalog /Dests, instead of warning that it wasn't applied. Estimates unchanged.
+- **2026-10-27 (M3, #3425):** A file named with open parameters, as help systems start a PDF reader (`manual.pdf#nameddest=Intro`, `#page=12` or `#Intro`), opens at that destination instead of failing to read `manual.pdf#…`: at launch, when another launch hands it over, and in its tab when it is already open. Other parameters are ignored. The app and `link_open` now also apply a GoToR link's named destination, looked up in the target's /Names /Dests or catalog /Dests, instead of warning that it wasn't applied; the app looks names up off the UI thread. `doc_open` reports the destination of a path with open parameters. Estimates unchanged.
 - **2026-10-27 (M10, OCR models):** Model staging downloads and verifies the ONNX pair after the upstream RTEN URL brownout; runtime discovery prefers complete ONNX pairs per directory, retains complete RTEN fallback and preserves directory precedence.
 - **2026-10-24 (M10, #4158 partial):** Word, HTML, RTF and PowerPoint export keep a block that continues another on its line (an italic case name, a link, a superscript) as a run in its own style inside that paragraph, with the source's word space, instead of a paragraph of its own. Style changes that wrap onto the next line still split paragraphs (the reading blocks keep style boundaries). Estimates unchanged.
 - **2026-10-24 (M3, window move on Wayland, #3970 follow-up):** After a move or resize by PdfCraft's own title bar or edges, the button release given back to egui goes before the pointer leaving the window, so hover no longer sticks at the old place until the pointer moves. Found by CodeRabbit in review of #3970; a unit test covers it. Estimates unchanged.

crates/ui-egui/src/app.rs

@@ -100,6 +100,8 @@ impl PdfCraftApp {
             #[cfg(not(target_arch = "wasm32"))]
             pending_opens: Vec::new(),
             #[cfg(not(target_arch = "wasm32"))]
+            pending_destinations: Vec::new(),
+            #[cfg(not(target_arch = "wasm32"))]
             next_open_token: 0,
             #[cfg(all(test, not(target_arch = "wasm32")))]
             open_prepare_gate: None,
@@ -353,6 +355,7 @@ impl eframe::App for PdfCraftApp {
                 worker.set_context(ctx);
             }
             self.poll_pending_opens();
+            self.poll_pending_destinations();
         }
         // Chinese wants its own faces before the Japanese ones (one baseline per line).
         let cjk = theme::CjkPreference::for_language(lang.code());

crates/ui-egui/src/app/files.rs

@@ -553,7 +553,11 @@ impl PdfCraftApp {
             }
             return OpenOutcome::Focused;
         }
-        if self.pending_opens.iter().any(|p| p.path.as_deref().is_some_and(|p| same_file(p, path))) {
+        if let Some(pending) = self.pending_opens.iter_mut().find(|p| p.path.as_deref().is_some_and(|p| same_file(p, path))) {
+            // Asked for another place before it finished opening: it opens at the latest one.
+            if after_open.is_some() {
+                pending.after_open = after_open;
+            }
             return OpenOutcome::Pending;
         }
         let name = std::path::Path::new(path).file_name().map(|n| n.to_string_lossy().into_owned()).unwrap_or_else(|| path.to_string());

crates/ui-egui/src/app/links.rs

@@ -72,19 +72,58 @@ impl PdfCraftApp {
     }
 
     /// Show `destination` in the tab at `index`: a document just opened from a link or with open
-    /// parameters (#3425), or one already open that such a link or launch names.
+    /// parameters (#3425), or one already open that such a link or launch names. The latest request
+    /// for a document wins over a named destination still being looked up.
     pub(super) fn apply_destination_at(&mut self, index: usize, destination: pdfcraft_render::RemoteDestination) {
-        let Some(view) = self.views.get_mut(index) else { return };
-        let Some(doc) = self.session.get(view.id) else { return };
+        let Some(id) = self.views.get(index).map(|view| view.id) else { return };
+        #[cfg(not(target_arch = "wasm32"))]
+        self.pending_destinations.retain(|pending| pending.doc != id);
         let destination = match destination {
             pdfcraft_render::RemoteDestination::Named(name) => {
-                match pdfcraft_render::named_destination(doc.bytes.clone(), doc.password.as_deref(), &name) {
-                    Some((page, dest)) => pdfcraft_render::RemoteDestination::Page { page, view: dest },
-                    None => pdfcraft_render::RemoteDestination::Named(name),
+                let Some(doc) = self.session.get(id) else { return };
+                let (bytes, password) = (doc.bytes.clone(), doc.password.clone());
+                // Live, the name tree is read off the UI thread; startup and tests stay inline.
+                #[cfg(not(target_arch = "wasm32"))]
+                if let Some(ctx) = self.ctx.clone().filter(|_| !self.run_inline) {
+                    let (sender, receiver) = std::sync::mpsc::channel();
+                    let (work_bytes, work_password, work_name) = (bytes.clone(), password.clone(), name.clone());
+                    let work = move || {
+                        let _ = sender.send(pdfcraft_render::named_destination(work_bytes, work_password.as_deref(), &work_name));
+                        ctx.request_repaint();
+                    };
+                    if std::thread::Builder::new().name("pdfcraft-named-destination".into()).spawn(work).is_ok() {
+                        self.pending_destinations.push(PendingDestination { doc: id, name, receiver });
+                        return;
+                    }
                 }
+                found_destination(pdfcraft_render::named_destination(bytes, password.as_deref(), &name), name)
             }
             other => other,
         };
+        self.show_destination_at(index, destination);
+    }
+
+    /// Show each named destination whose lookup has finished, in its document's tab.
+    #[cfg(not(target_arch = "wasm32"))]
+    pub(crate) fn poll_pending_destinations(&mut self) {
+        for pending in std::mem::take(&mut self.pending_destinations) {
+            let found = match pending.receiver.try_recv() {
+                Ok(found) => found,
+                Err(std::sync::mpsc::TryRecvError::Empty) => {
+                    self.pending_destinations.push(pending);
+                    continue;
+                }
+                Err(std::sync::mpsc::TryRecvError::Disconnected) => None,
+            };
+            if let Some(index) = self.views.iter().position(|view| view.id == pending.doc) {
+                self.show_destination_at(index, found_destination(found, pending.name));
+            }
+        }
+    }
+
+    fn show_destination_at(&mut self, index: usize, destination: pdfcraft_render::RemoteDestination) {
+        let Some(view) = self.views.get_mut(index) else { return };
+        let Some(doc) = self.session.get(view.id) else { return };
         let warning = match destination {
             pdfcraft_render::RemoteDestination::Default => None,
             pdfcraft_render::RemoteDestination::Named(_) => Some("The linked PDF opened, but its named destination was not applied."),
@@ -140,3 +179,12 @@ impl PdfCraftApp {
         }
     }
 }
+
+/// A named destination's lookup result as a destination to show: its page, or the name again when
+/// the document doesn't define it, which shows a warning.
+fn found_destination(found: Option<(usize, pdfcraft_render::DestView)>, name: String) -> pdfcraft_render::RemoteDestination {
+    match found {
+        Some((page, view)) => pdfcraft_render::RemoteDestination::Page { page, view },
+        None => pdfcraft_render::RemoteDestination::Named(name),
+    }
+}

crates/ui-egui/src/lib.rs

@@ -229,6 +229,15 @@ struct PendingOpen {
     then: Option<&'static str>,
 }
 
+/// A named destination being looked up off the UI thread: reading a large document's name tree
+/// takes a noticeable moment.
+#[cfg(not(target_arch = "wasm32"))]
+struct PendingDestination {
+    doc: DocId,
+    name: String,
+    receiver: std::sync::mpsc::Receiver<Option<(usize, pdfcraft_render::DestView)>>,
+}
+
 pub struct PdfCraftApp {
     /// Tools side and pane widths; which panes are open is `left_open` and `right`.
     pub side_panels: side_panels::SidePanels,
@@ -353,6 +362,8 @@ pub struct PdfCraftApp {
     #[cfg(not(target_arch = "wasm32"))]
     pending_opens: Vec<PendingOpen>,
     #[cfg(not(target_arch = "wasm32"))]
+    pending_destinations: Vec<PendingDestination>,
+    #[cfg(not(target_arch = "wasm32"))]
     next_open_token: u64,
     #[cfg(all(test, not(target_arch = "wasm32")))]
     open_prepare_gate: Option<std::sync::Arc<open_worker::PrepareGate>>,

crates/ui-egui/tests/it/document_links.rs

@@ -213,14 +213,14 @@ fn a_gotor_link_to_a_named_destination_opens_at_its_page() {
     for (destination, page) in [("/there", 2), ("(here)", 1)] {
         let mut h = remote_harness(Some(dir.join("source.pdf").to_string_lossy().into_owned()), "target.pdf", destination);
         click_remote_link(&mut h);
-        support::wait_until(&mut h, "remote document", |app| app.views.len() == 2);
-        assert_eq!(h.state().views[1].current, page, "{destination}");
+        // The name is looked up off the UI thread, so the tab may open before it moves there.
+        support::wait_until(&mut h, "remote document at its destination", |app| app.views.len() == 2 && app.views[1].current == page);
         assert_eq!(h.state().toast, None, "{destination}: applied, so nothing to warn about");
     }
     // A name the target doesn't define opens it at its first page, with the warning.
     let mut h = remote_harness(Some(dir.join("source.pdf").to_string_lossy().into_owned()), "target.pdf", "/elsewhere");
     click_remote_link(&mut h);
-    support::wait_until(&mut h, "remote document", |app| app.views.len() == 2);
+    support::wait_until(&mut h, "remote document and the warning", |app| app.views.len() == 2 && app.toast.is_some());
     assert_eq!(h.state().views[1].current, 0);
     assert!(h.state().toast.as_ref().is_some_and(|(text, _)| text.contains("named destination was not applied")), "{:?}", h.state().toast);
 }

crates/ui-egui/tests/it/open_action.rs

@@ -243,10 +243,23 @@ fn open_parameters_handed_to_the_running_app_show_their_destination() {
         app
     });
     h.run_steps(4);
+    // Asked twice before it has opened, it opens at the place asked for last.
+    assert_eq!(h.state_mut().open_path(&format!("{path}#page=5")), OpenOutcome::Pending);
     assert_eq!(h.state_mut().open_path(&format!("{path}#nameddest=Load Flow")), OpenOutcome::Pending);
-    crate::support::wait_until(&mut h, "the manual", |app| app.views.len() == 1);
-    assert_eq!(h.state().views[0].current, 3);
+    crate::support::wait_until(&mut h, "the manual at Load Flow", |app| app.views.len() == 1 && app.views[0].current == 3);
     // Asked again for a place in the open file, its tab goes there instead of opening it again.
     assert_eq!(h.state_mut().open_path(&format!("{path}#page=2")), OpenOutcome::Focused);
     assert_eq!((h.state().views.len(), h.state().views[0].current), (1, 1));
+    // A name is looked up off the UI thread: the tab moves once the lookup is in.
+    assert_eq!(h.state_mut().open_path(&format!("{path}#nameddest=Load Flow")), OpenOutcome::Focused);
+    assert_eq!(h.state().views[0].current, 1, "not yet");
+    crate::support::wait_until(&mut h, "Load Flow", |app| app.views[0].current == 3);
+    // A page asked for while a name is still being looked up wins: the lookup's answer is dropped.
+    assert_eq!(h.state_mut().open_path(&format!("{path}#nameddest=intro")), OpenOutcome::Focused);
+    assert_eq!(h.state_mut().open_path(&format!("{path}#page=5")), OpenOutcome::Focused);
+    for _ in 0..25 {
+        h.run_steps(1);
+        std::thread::sleep(std::time::Duration::from_millis(20));
+    }
+    assert_eq!(h.state().views[0].current, 4);
 }