feat(overlay): blocking progress overlay + SPV-sync hard-block

docs/user-stories.md

@@ -17,6 +17,7 @@ See [docs/personas/](personas/) for full persona descriptions.
 - [Developer and Power Tools (DEV)](#developer-and-power-tools-dev)
 - [Network and Settings (NET)](#network-and-settings-net)
 - [Programmatic Access (MCP)](#programmatic-access-mcp)
+- [User Experience (UX)](#user-experience-ux)
 
 ---
 
@@ -1121,3 +1122,27 @@ As an AI agent, I want MCP server access so that I can assist users with wallet
 - Bearer token authentication for HTTP mode.
 - Network verification guard prevents cross-network mistakes.
 - Tools expose wallet, identity, and platform operations.
+
+---
+
+## User Experience (UX)
+
+### UX-001: Blocking progress overlay for unsafe-to-interrupt operations [Implemented]
+**Persona:** Alex, Priya, Jordan
+
+As a user, while a long operation that is unsafe to interrupt is running (broadcasting a state transition, signing, key import, a multi-step registration, a network migration), I want to see a clear please-wait block over the whole window so that I understand the app is busy and cannot accidentally fire a conflicting second action.
+
+- A full-window dimming overlay with an indeterminate spinner and an optional "Step N of M" counter and description appears while the operation runs, and lowers automatically when it finishes (success or error).
+- All interaction beneath the block is suppressed: pointer clicks hit a sink, and keyboard/text input is claimed at frame start so nothing reaches a focused field beneath (FR-8 / QA-001). The block is never dismissable by Esc, Enter, Space, or Tab.
+- The block yields to a passphrase prompt: when a secret prompt is shown above the overlay it keeps the keyboard (Enter/Esc/Tab) so the user can still authenticate or cancel (SEC-004).
+- Honest escalation, never a fake exit: after 30 s a calm "This is taking longer than usual." line appears; after 120 s with no progress it escalates to "This is taking much longer than expected…" and logs a one-shot developer warning. For these unsafe-to-interrupt operations there is no background/dismiss button — the safety guarantee is that every blocked operation is bounded and always lowers the block through the normal path. _(Exception: the startup/Connect SPV-sync block of UX-002 is unbounded but read-only, so it ships an always-visible "Continue in the background" escape instead.)_
+
+### UX-002: Blocking SPV-sync overlay with a "continue in the background" escape [Implemented]
+**Persona:** Alex, Priya, Jordan
+
+As a user, while the app connects to and syncs the Dash chain on startup or after I press Connect, I want a clear please-wait block so I know it is working — and because that sync can wait indefinitely for peers, I want an always-visible "Continue in the background" button so I am never trapped behind it.
+
+- While that startup/Connect sync is getting connected, a full-window block appears with a plain please-wait sentence ("Connecting to the Dash network." / "Syncing with the Dash network.") and a friendly progress indicator ("Step N of 5") — no blockchain jargon, raw heights, or percentages.
+- The block always offers a secondary "Continue in the background" button. Clicking it lowers the block; sync keeps running in the background (it is read-only and strands nothing), and the block is not re-raised for the rest of that sync episode.
+- The block is scoped to *user-initiated* sync (startup auto-start / Connect): it lowers on its own when the chain becomes usable (Synced) or fails (Error), and an **ambient** reconnect or per-block catch-up afterward does not block a working user. Pressing Connect (or a fresh startup) blocks again.
+- This is the overlay's first real adopter (PR #863). Unlike the unsafe-to-interrupt operations in UX-001, SPV sync is **unbounded but safe to background** — so its C2 "never trap the user" guarantee is met by the always-on escape, not by operation boundedness.

src/context/connection_status.rs

@@ -412,6 +412,15 @@ impl ConnectionStatus {
         self.overall_state.load(Ordering::Relaxed).into()
     }
 
+    /// Test seam: force the overall connection state directly. Bypasses
+    /// [`Self::refresh_state`] so a test that drives a consumer in isolation (not
+    /// the throttled frame loop) sees a stable state. Compiled only under the
+    /// `testing` feature.
+    #[cfg(feature = "testing")]
+    pub fn set_overall_state(&self, state: OverallConnectionState) {
+        self.overall_state.store(state as u8, Ordering::Relaxed);
+    }
+
     /// Recompute the overall connection state from the individual subsystem
     /// flags.
     ///
@@ -631,6 +640,30 @@ pub fn spv_phase_summary(progress: &SpvSyncProgress) -> String {
     "syncing...".to_string()
 }
 
+/// Map the currently-active SPV sync phase to a 1-based step number for the
+/// blocking overlay's "Step N of 5" counter — Headers=1, Masternodes=2,
+/// Filter Headers=3, Filters=4, Blocks=5 — or `None` when no phase is actively
+/// syncing yet. Mirrors the pipeline order of [`spv_phase_summary`].
+pub fn spv_phase_step(progress: &SpvSyncProgress) -> Option<u32> {
+    let is_syncing = |state: SyncState| state == SyncState::Syncing;
+    if progress.headers().is_ok_and(|p| is_syncing(p.state())) {
+        Some(1)
+    } else if progress.masternodes().is_ok_and(|p| is_syncing(p.state())) {
+        Some(2)
+    } else if progress
+        .filter_headers()
+        .is_ok_and(|p| is_syncing(p.state()))
+    {
+        Some(3)
+    } else if progress.filters().is_ok_and(|p| is_syncing(p.state())) {
+        Some(4)
+    } else if progress.blocks().is_ok_and(|p| is_syncing(p.state())) {
+        Some(5)
+    } else {
+        None
+    }
+}
+
 fn pct(current: u32, target: u32) -> u32 {
     if target == 0 {
         0
@@ -677,6 +710,21 @@ mod tests {
         assert!(status.spv_sync_progress().is_none());
     }
 
+    /// F-SPV-2 — the blocking overlay's "Step N of 5" counter maps to the active
+    /// phase, and the summary reflects the live headers phase.
+    #[test]
+    fn spv_phase_step_and_summary_track_active_phase() {
+        let progress = syncing_progress();
+        assert_eq!(spv_phase_step(&progress), Some(1), "headers phase → step 1");
+        assert!(
+            spv_phase_summary(&progress).starts_with("Headers: 5000 / 10000"),
+            "summary reflects the live headers phase"
+        );
+
+        // No phase actively syncing → no step (the overlay shows the generic line).
+        assert_eq!(spv_phase_step(&SpvSyncProgress::default()), None);
+    }
+
     #[test]
     fn spv_status_snapshot_reflects_live_state() {
         let status = ConnectionStatus::new();

src/ui/components/README.md

@@ -34,6 +34,7 @@ Concise catalog of all reusable UI components. Consult before creating new UI el
 | Component | File | Description |
 |-----------|------|-------------|
 | `MessageBanner` | `message_banner.rs` | Global error/warning/success/info banners. `set_global()`, `with_details()`, auto-dismiss. Extensions: `OptionBannerExt`, `OptionBannerShowExt`, `ResultBannerExt` |
+| `ProgressOverlay` | `progress_overlay.rs` | Full-screen blocking progress overlay: spinner, optional step counter, generic buttons (`with_button(id, label)`), 120s watchdog. Global path: `show_global()` / `render_global()`, claims input each frame. Companions: `OverlayConfig`, `OverlayHandle`, `OptionOverlayExt`, `ProgressOverlayResponse` |
 
 ## Styled Components (`styled.rs`)
 

src/ui/components/mod.rs

@@ -13,6 +13,7 @@ pub mod left_wallet_panel;
 pub mod message_banner;
 pub mod passphrase_modal;
 pub mod password_input;
+pub mod progress_overlay;
 pub mod secret_prompt_host;
 pub mod selection_dialog;
 pub mod styled;
@@ -27,4 +28,7 @@ pub use message_banner::{
     BannerHandle, BannerStatus, MessageBanner, MessageBannerResponse, OptionBannerExt,
     OptionBannerShowExt, ResultBannerExt,
 };
+pub use progress_overlay::{
+    OptionOverlayExt, OverlayConfig, OverlayHandle, ProgressOverlay, ProgressOverlayResponse,
+};
 pub use secret_prompt_host::{ActivePrompt, EguiSecretPromptHost, QueuedPrompt};

src/ui/components/passphrase_modal.rs

@@ -139,6 +139,11 @@ pub fn passphrase_modal(
     let window_response = egui::Window::new(config.window_title)
         .collapsible(false)
         .resizable(false)
+        // Render on Order::Foreground so the prompt stays above the blocking
+        // progress overlay (also Foreground, but drawn earlier this frame) — the
+        // overlay must never cover a secret prompt it triggered (R-1, SEC-002).
+        // Created after the overlay and focus-raised, so it wins within Foreground.
+        .order(egui::Order::Foreground)
         .anchor(egui::Align2::CENTER_CENTER, egui::Vec2::ZERO)
         .open(&mut window_is_open)
         .frame(egui::Frame {