Skip to content

armgit / Cap

Public Imported from GitHub
0

Open source Loom alternative. Beautiful, shareable screen recordings.

42.2 KB
Raw Blame
//! `cap-desktop://` deep-link actions -- the gpui port of
//! `apps/desktop/src-tauri/src/deeplink_actions.rs`.
//!
//! The URL grammar is byte-identical to the Tauri app's: an action deep link
//! is `<scheme>://action?value=<url-encoded JSON>`, where the JSON is the
//! serde form of [`DeepLinkAction`] (externally tagged, `snake_case` variant
//! names). The scheme itself is deliberately not checked -- the Tauri parser
//! (`deeplink_actions.rs:155-183`) discriminates on the *host* alone, so
//! `cap-desktop://` and `cap://` both work, and any URL whose host is not
//! `action` is either "not ours" ([`ActionParseFromUrlError::NotAction`], the
//! login callback's host is `auth`) or malformed. No URL is ever *built* from
//! these parts, so the userinfo/port authority-injection class that bit the
//! web session endpoint (2026-08, the `[email protected]` takeover) has no
//! sink here -- but the host match is still exact, never a substring, and every
//! parse failure is a dropped action, never a panic: this input arrives
//! straight from the OS on behalf of whatever wrote the URL.
//!
//! Delivery, and how it maps onto the Tauri app's two paths:
//!
//! * **App already running.** Tauri receives the URL through
//!   `tauri_plugin_deep_link`'s `on_open_url` (`lib.rs:5601-5603`); on macOS
//!   that plugin is a GURL AppleEvent handler, and this app installs its own in
//!   [`crate::platform::install_url_scheme_handler`], which forwards every URL
//!   to [`submit_deep_link`]. A URL opened while the app runs never spawns a
//!   second instance on macOS -- the AppleEvent goes to the running process.
//! * **App launched by the URL.** Tauri's single-instance plugin hands the new
//!   launch's `cap-desktop://` argv to the surviving old instance
//!   (`lib.rs:5193-5204`). Linux and Windows forward action URLs to the
//!   surviving instance; [`init`] reads argv on the initial launch. On macOS the
//!   launch URL additionally arrives as the same GURL event once the run loop
//!   starts; both roads feed one channel, and the channel buffers until the
//!   drain task exists, so neither ordering loses the action.
//!
//! Execution mirrors `DeepLinkActionExecutor` (`deeplink_actions.rs:69-105`):
//! a single queue, actions run strictly in arrival order. Over there the
//! consumer is a dedicated thread `block_on`-ing each action; here it is one
//! foreground task draining into `cx.update`, the same channel discipline the
//! tray and the global hotkeys use.

use std::collections::HashMap;
use std::path::PathBuf;
use std::sync::OnceLock;

use cap_recording::feeds::camera::DeviceOrModelID;
use cap_recording::sources::screen_capture::ScreenCaptureTarget;
use gpui::App;
use reqwest::Url;
use serde::{Deserialize, Serialize};

use crate::{
    app_windows,
    feeds::{Feeds, SelectedCamera},
    library, recording,
    session::{Phase, RecordingSession},
    settings_window::Page,
};

/// `CaptureArea` (`deeplink_actions.rs:18-25`). Debug-gated exactly as it is
/// over there: area capture via deep link is a harness affordance, not a
/// shipping surface.
#[cfg(debug_assertions)]
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
pub struct CaptureArea {
    screen: String,
    x: f64,
    y: f64,
    width: f64,
    height: f64,
}

/// `CaptureMode` (`deeplink_actions.rs:27-36`): the screen and window are
/// addressed by *name*, resolved against the live target lists at execution
/// time, matching the Tauri lookup verbatim.
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum CaptureMode {
    Screen(String),
    Window(String),
    #[cfg(debug_assertions)]
    Area(Box<CaptureArea>),
    #[cfg(debug_assertions)]
    CameraOnly,
}

/// `CameraPreviewShape` (`src-tauri/src/camera.rs:161-168`), mirrored here so
/// the debug `set_camera_preview_state` payload deserializes identically.
#[cfg(debug_assertions)]
#[derive(Debug, Default, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum CameraPreviewShape {
    #[default]
    Round,
    Square,
    Full,
}

/// `CameraPreviewState` (`src-tauri/src/camera.rs:170-177`). `background_blur`
/// keeps its `#[serde(default)]` and its `cap_project` type, so the accepted
/// JSON is the Tauri app's exactly.
#[cfg(debug_assertions)]
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
pub struct CameraPreviewState {
    pub size: f32,
    pub shape: CameraPreviewShape,
    pub mirrored: bool,
    #[serde(default)]
    pub background_blur: cap_project::BackgroundBlurMode,
}

/// `DeepLinkAction` (`deeplink_actions.rs:38-67`), variant for variant,
/// including which ones exist only under `debug_assertions`. `mode` uses
/// `cap_recording::RecordingMode` -- the exact type the Tauri enum embeds --
/// so `"studio"`/`"instant"`/`"screenshot"` all *parse*; the screenshot case
/// is then refused at execution with the Tauri app's own error (its
/// `start_recording` returns "Use take_screenshot for screenshots",
/// `src-tauri/src/recording.rs:1699-1704`).
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum DeepLinkAction {
    StartRecording {
        capture_mode: CaptureMode,
        camera: Option<DeviceOrModelID>,
        mic_label: Option<String>,
        capture_system_audio: bool,
        mode: cap_recording::RecordingMode,
    },
    StopRecording,
    #[cfg(debug_assertions)]
    PauseRecording,
    #[cfg(debug_assertions)]
    ResumeRecording,
    #[cfg(debug_assertions)]
    OpenCamera {
        camera: DeviceOrModelID,
    },
    #[cfg(debug_assertions)]
    SetCameraPreviewState {
        state: CameraPreviewState,
    },
    OpenEditor {
        project_path: PathBuf,
    },
    OpenSettings {
        page: Option<String>,
    },
}

/// `ActionParseFromUrlError` (`deeplink_actions.rs:148-153`).
#[derive(Debug, PartialEq, Eq)]
pub enum ActionParseFromUrlError {
    ParseFailed(String),
    Invalid,
    NotAction,
}

impl TryFrom<&Url> for DeepLinkAction {
    type Error = ActionParseFromUrlError;

    /// `deeplink_actions.rs:158-182`, verbatim. The `file://` branch is the
    /// macOS "open with Cap" path; this binary registers no document types so
    /// only tests reach it today, but the grammar stays whole.
    fn try_from(url: &Url) -> Result<Self, Self::Error> {
        #[cfg(target_os = "macos")]
        if url.scheme() == "file" {
            return url
                .to_file_path()
                .map(|project_path| Self::OpenEditor { project_path })
                .map_err(|_| ActionParseFromUrlError::Invalid);
        }

        match url.domain() {
            Some("action") => {}
            Some(_) => return Err(ActionParseFromUrlError::NotAction),
            None => return Err(ActionParseFromUrlError::Invalid),
        }

        let params = url.query_pairs().collect::<HashMap<_, _>>();
        let json_value = params
            .get("value")
            .ok_or(ActionParseFromUrlError::Invalid)?;
        let action: Self = serde_json::from_str(json_value)
            .map_err(|e| ActionParseFromUrlError::ParseFailed(e.to_string()))?;
        Ok(action)
    }
}

#[derive(Debug, PartialEq)]
enum QueuedAction {
    DeepLink(DeepLinkAction),
    #[cfg(any(target_os = "macos", target_os = "windows"))]
    Reopen,
}

impl QueuedAction {
    fn execute(self, cx: &mut App) -> Result<(), String> {
        match self {
            Self::DeepLink(action) => action.execute(cx),
            #[cfg(any(target_os = "macos", target_os = "windows"))]
            Self::Reopen => {
                app_windows::handle_dock_reopen(cx);
                Ok(())
            }
        }
    }
}

/// The action queue. Unbounded and created on first touch, so URLs submitted
/// before [`init`] runs (the launch AppleEvent, argv) wait for the drain task
/// instead of being dropped -- the buffering the Tauri app gets from its
/// executor being managed before `on_open_url` is wired.
fn channel() -> &'static (flume::Sender<QueuedAction>, flume::Receiver<QueuedAction>) {
    static CHANNEL: OnceLock<(flume::Sender<QueuedAction>, flume::Receiver<QueuedAction>)> =
        OnceLock::new();
    CHANNEL.get_or_init(flume::unbounded)
}

pub(crate) fn submit_action(action: DeepLinkAction) {
    tracing::info!("queueing deep link action");
    if channel().0.send(QueuedAction::DeepLink(action)).is_err() {
        tracing::error!("failed to queue deep link action");
    }
}

#[cfg(any(target_os = "macos", target_os = "windows"))]
pub(crate) fn submit_reopen() -> bool {
    channel().0.send(QueuedAction::Reopen).is_ok()
}

/// The one entry point for a URL handed over by the OS -- what
/// `platform::install_url_scheme_handler`'s AppleEvent handler calls. Safe
/// from any thread; does no gpui work itself.
///
/// Every URL is first forwarded to the sign-in flow ([`crate::auth`]), whose
/// slot only exists during an active sign-in and filters for its own
/// `token`/`api_key` parameters -- the pre-existing behavior of the handler,
/// unchanged. Action parsing happens on top.
#[cfg(any(target_os = "macos", target_os = "windows"))]
pub fn submit_deep_link(raw: &str) {
    crate::auth::submit_deep_link(raw);
    submit_action_url(raw);
}

/// Parse-and-queue half of [`submit_deep_link`]; also the argv path in
/// [`init`], which skips the auth forward because `main` already routes
/// token-bearing arguments there.
///
/// Error reporting mirrors `deeplink_actions::handle`
/// (`deeplink_actions.rs:107-133`) with one deliberate deviation: the failed
/// URL's *content* is never logged, only its shape -- an auth callback that
/// lands in the `Invalid` arm must not write its token into the log.
fn submit_action_url(raw: &str) {
    if raw.is_empty() {
        return;
    }
    let Ok(url) = Url::parse(raw) else {
        tracing::debug!("deep link is not a URL; ignored");
        return;
    };
    match DeepLinkAction::try_from(&url) {
        Ok(action) => submit_action(action),
        Err(ActionParseFromUrlError::ParseFailed(message)) => {
            tracing::error!(
                scheme = url.scheme(),
                host = url.host_str().unwrap_or_default(),
                %message,
                "failed to parse deep link action"
            );
        }
        Err(ActionParseFromUrlError::Invalid) => {
            tracing::error!(
                scheme = url.scheme(),
                host = url.host_str().unwrap_or_default(),
                "invalid deep link format"
            );
        }
        // Likely login action, not handled here -- the auth slot got it.
        Err(ActionParseFromUrlError::NotAction) => {}
    }
}

/// Wire the executor: scan the initial launch argv for action URLs, then
/// start the drain task that runs each queued action on the main thread with
/// a clean borrow. Called once from [`crate::app_windows::init`], after the
/// window registry the actions dispatch into exists.
pub fn init(cx: &mut App) {
    for argument in std::env::args().skip(1) {
        if argument.starts_with("cap-desktop://") || argument.starts_with("cap://") {
            submit_action_url(&argument);
        }
    }

    let rx = channel().1.clone();
    cx.spawn(async move |cx| {
        while let Ok(action) = rx.recv_async().await {
            cx.update(|cx| {
                tracing::info!("executing Cap action");
                if let Err(error) = action.execute(cx) {
                    tracing::error!(%error, "failed to handle deep link action");
                }
            });
        }
    })
    .detach();
}

fn dispatch_recording_stop<C>(
    phase: Phase,
    clean_capture_owned: bool,
    context: &mut C,
    cancel_preflight: impl FnOnce(&mut C),
    stop_session: impl FnOnce(&mut C),
) {
    if phase == Phase::Idle && clean_capture_owned {
        cancel_preflight(context);
    } else {
        stop_session(context);
    }
}

impl DeepLinkAction {
    /// `DeepLinkAction::execute` (`deeplink_actions.rs:186-296`), arm for arm,
    /// against this app's counterparts: the session and feeds globals where
    /// the Tauri arms call commands on `ArcLock<App>`, and
    /// [`crate::app_windows`] where they call `ShowCapWindow`.
    pub fn execute(self, cx: &mut App) -> Result<(), String> {
        match self {
            DeepLinkAction::StartRecording {
                capture_mode,
                camera,
                mic_label,
                capture_system_audio,
                mode,
            } => {
                // The name -> target resolution, verbatim from
                // `deeplink_actions.rs:200-231`.
                let capture_target: ScreenCaptureTarget = match capture_mode {
                    CaptureMode::Screen(name) => cap_recording::screen_capture::list_displays()
                        .into_iter()
                        .find(|(s, _)| s.name == name)
                        .map(|(s, _)| ScreenCaptureTarget::Display { id: s.id })
                        .ok_or(format!("No screen with name \"{}\"", name))?,
                    CaptureMode::Window(name) => cap_recording::screen_capture::list_windows()
                        .into_iter()
                        .find(|(w, _)| w.name == name)
                        .map(|(w, _)| ScreenCaptureTarget::Window { id: w.id })
                        .ok_or(format!("No window with name \"{}\"", name))?,
                    #[cfg(debug_assertions)]
                    CaptureMode::Area(area) => {
                        if area.width <= 0.0 || area.height <= 0.0 {
                            return Err("Area width and height must be positive".to_string());
                        }
                        let screen = cap_recording::screen_capture::list_displays()
                            .into_iter()
                            .find(|(display, _)| display.name == area.screen)
                            .map(|(display, _)| display.id)
                            .ok_or(format!("No screen with name \"{}\"", area.screen))?;
                        ScreenCaptureTarget::Area {
                            screen,
                            bounds: scap_targets::bounds::LogicalBounds::new(
                                scap_targets::bounds::LogicalPosition::new(area.x, area.y),
                                scap_targets::bounds::LogicalSize::new(area.width, area.height),
                            ),
                        }
                    }
                    #[cfg(debug_assertions)]
                    CaptureMode::CameraOnly => ScreenCaptureTarget::CameraOnly,
                };

                let mode = match mode {
                    cap_recording::RecordingMode::Studio => recording::RecordingMode::Studio,
                    cap_recording::RecordingMode::Instant => recording::RecordingMode::Instant,
                    // The Tauri parser admits it and its `start_recording`
                    // refuses it (`recording.rs:1699-1704`); same split here.
                    cap_recording::RecordingMode::Screenshot => {
                        return Err("Use take_screenshot for screenshots".to_string());
                    }
                };

                let main = cx.global::<app_windows::AppWindows>().main;
                let permit = main
                    .update(cx, |view, _, cx| view.prepare_deep_link_start(cx))
                    .map_err(|_| "The recording window is unavailable".to_string())??;
                let selection = camera.clone().map(camera_selection);
                if !permit.is_current(cx) {
                    let _ = main.update(cx, |view, _, _| view.finish_deep_link_start(&permit));
                    return Err("Recording preparation is no longer current".into());
                }
                Feeds::global(cx).update(cx, |feeds, cx| {
                    feeds.set_camera(selection, cx);
                    feeds.set_microphone(mic_label.clone(), cx);
                });

                // Deferred behind `set_camera`'s own deferred
                // `open_camera_window`, so a studio start finds the bubble
                // already open and excludes it from capture
                // (`begin_recording`'s `camera_window_number` read). gpui
                // flushes deferred callbacks in FIFO order.
                cx.defer(move |cx| {
                    if !permit.is_current(cx) {
                        let _ = main.update(cx, |view, _, _| view.finish_deep_link_start(&permit));
                        return;
                    }
                    let (camera_feed, mic_feed, mic_meter, input_readiness, device_settings) = {
                        let feeds = Feeds::global(cx);
                        feeds.update(cx, |feeds, cx| feeds.resume_camera_preview(cx));
                        let feeds = feeds.read(cx);
                        (
                            feeds.camera_actor(),
                            feeds.mic_actor(),
                            feeds.mic_meter(),
                            feeds.input_readiness(),
                            feeds.requested_device_settings(),
                        )
                    };
                    if main
                        .update(cx, |view, _, cx| {
                            view.start_recording_config_with_permit(
                                recording::StartConfig {
                                    mode,
                                    target: capture_target,
                                    device_settings,
                                    input_readiness,
                                    microphone: mic_label,
                                    camera,
                                    system_audio: capture_system_audio,
                                    excluded_windows: Vec::new(),
                                    camera_feed,
                                    mic_feed,
                                    mic_meter,
                                    #[cfg(target_os = "linux")]
                                    linux_instant_camera: None,
                                    start_gate: None,
                                },
                                permit.clone(),
                                cx,
                            )
                        })
                        .is_err()
                    {
                        permit.cancel();
                    }
                });
                Ok(())
            }
            DeepLinkAction::StopRecording => {
                let main = cx.global::<app_windows::AppWindows>().main;
                let _ = main.update(cx, |view, _, cx| {
                    view.cancel_deep_link_start();
                    cx.notify();
                });
                let session = RecordingSession::global(cx);
                dispatch_recording_stop(
                    session.read(cx).phase,
                    app_windows::clean_capture_owned(cx),
                    cx,
                    app_windows::cancel_clean_capture,
                    |cx| {
                        if session.read(cx).phase == crate::session::Phase::Idle {
                            app_windows::abort_editor_recording_flow(cx);
                        } else {
                            session.update(cx, |session, cx| session.stop(cx));
                        }
                    },
                );
                Ok(())
            }
            // `pause_recording` / `resume_recording`
            // (`src-tauri/src/recording.rs:2421-2444`) are directional and
            // no-ops without a live recording; the session only exposes the
            // bar's toggle, so the direction is enforced here.
            #[cfg(debug_assertions)]
            DeepLinkAction::PauseRecording => {
                RecordingSession::global(cx).update(cx, |session, cx| {
                    if matches!(
                        session.phase,
                        crate::session::Phase::Recording { paused: false }
                    ) {
                        session.toggle_pause(cx);
                    }
                });
                Ok(())
            }
            #[cfg(debug_assertions)]
            DeepLinkAction::ResumeRecording => {
                RecordingSession::global(cx).update(cx, |session, cx| {
                    if session.is_paused() {
                        session.toggle_pause(cx);
                    }
                });
                Ok(())
            }
            // `set_camera_input(Some)` + the native preview: `Feeds::set_camera`
            // is both halves here -- the gpui camera window *is* the native
            // preview, and `set_camera` opens it. The
            // `instant-mode-harness-camera-opened` emits are webview harness
            // signals with no consumer in this app.
            #[cfg(debug_assertions)]
            DeepLinkAction::OpenCamera { camera } => {
                let selection = camera_selection(camera);
                Feeds::global(cx).update(cx, |feeds, cx| feeds.set_camera(Some(selection), cx));
                Ok(())
            }
            // `set_camera_preview_state`: persist the state, then bounce the
            // bubble if it is up -- the gpui camera window reads its chrome
            // state at construction (`CameraWindow::new`), so a reopen is the
            // live-apply seam.
            #[cfg(debug_assertions)]
            DeepLinkAction::SetCameraPreviewState { state } => {
                let shape = match state.shape {
                    CameraPreviewShape::Round => crate::store::CameraShape::Round,
                    CameraPreviewShape::Square => crate::store::CameraShape::Square,
                    CameraPreviewShape::Full => crate::store::CameraShape::Full,
                };
                let background_blur = match state.background_blur {
                    cap_project::BackgroundBlurMode::Off => crate::store::BlurMode::Off,
                    cap_project::BackgroundBlurMode::Light => crate::store::BlurMode::Light,
                    cap_project::BackgroundBlurMode::Heavy => crate::store::BlurMode::Heavy,
                    cap_project::BackgroundBlurMode::Remove => crate::store::BlurMode::Remove,
                };
                crate::store::update(|persisted| {
                    persisted.camera_window = Some(crate::store::CameraWindowState {
                        size: state.size,
                        shape,
                        mirrored: state.mirrored,
                        background_blur,
                    });
                });
                if cx.global::<app_windows::AppWindows>().camera.is_some() {
                    app_windows::close_camera_window(cx);
                    app_windows::open_camera_window(cx);
                }
                Ok(())
            }
            // `open_project_from_path` (`src-tauri/src/lib.rs:6877-6907`):
            // studio bundles go to the editor after the status gate, instant
            // bundles open their mp4 in the system player and hide the main
            // window. The meta load is also the validation seam for this
            // OS-supplied path -- anything that is not a readable `.cap`
            // bundle fails here and opens nothing.
            DeepLinkAction::OpenEditor { project_path } => {
                use cap_project::{RecordingMeta, RecordingMetaInner, StudioRecordingStatus};

                if crate::library::is_screenshot_bundle(&project_path) {
                    cx.defer(move |cx| app_windows::open_screenshot_editor(project_path, cx));
                    return Ok(());
                }

                let meta =
                    RecordingMeta::load_for_project(&project_path).map_err(|v| v.to_string())?;
                match &meta.inner {
                    RecordingMetaInner::Studio(studio) => {
                        let status = studio.status();
                        if let StudioRecordingStatus::Failed { .. } = status {
                            return Err("Unable to open failed recording".to_string());
                        } else if let StudioRecordingStatus::InProgress = status {
                            return Err("Recording in progress".to_string());
                        }
                        // Deferred like `activate_recent`: `open_editor` opens
                        // a window, which must not happen from inside an
                        // entity update.
                        cx.defer(move |cx| app_windows::open_editor(project_path, cx));
                    }
                    RecordingMetaInner::Instant(_) => {
                        let mp4_path = project_path.join("content/output.mp4");
                        if mp4_path.exists() && mp4_path.is_file() {
                            library::open_with_system(&mp4_path, cx);
                            app_windows::hide_main_window(cx);
                        }
                    }
                }
                Ok(())
            }
            // `ShowCapWindow::Settings { page }`. The Tauri window navigates
            // to `/settings/{page}` and an unknown slug is a dead route; here
            // an unknown (or absent) slug lands on General, the settings
            // window's own default.
            DeepLinkAction::OpenSettings { page } => {
                let page = page
                    .as_deref()
                    .and_then(Page::from_slug)
                    .unwrap_or(Page::General);
                app_windows::open_settings(page, cx);
                Ok(())
            }
        }
    }
}

fn camera_selection(id: DeviceOrModelID) -> SelectedCamera {
    let info = cap_camera::list_cameras().find(|info| match &id {
        DeviceOrModelID::DeviceID(device) => info.device_id() == device,
        DeviceOrModelID::ModelID(model) => info.model_id() == Some(model),
    });
    SelectedCamera {
        device_id: info
            .as_ref()
            .map(|info| info.device_id().to_string())
            .unwrap_or_else(|| match &id {
                DeviceOrModelID::DeviceID(device) => device.clone(),
                DeviceOrModelID::ModelID(_) => String::new(),
            }),
        model_id: info
            .as_ref()
            .and_then(|info| info.model_id().cloned())
            .or_else(|| match &id {
                DeviceOrModelID::ModelID(model) => Some(model.clone()),
                DeviceOrModelID::DeviceID(_) => None,
            }),
        label: info
            .as_ref()
            .map(|info| info.display_name().to_string())
            .unwrap_or_else(|| match &id {
                DeviceOrModelID::DeviceID(device) => device.clone(),
                DeviceOrModelID::ModelID(_) => "Camera".to_string(),
            }),
        id,
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn stop_dispatch_cancels_idle_preflight_and_preserves_live_session_stop() {
        for phase in [
            Phase::Idle,
            Phase::Starting,
            Phase::Recording { paused: false },
            Phase::Recording { paused: true },
            Phase::Stopping,
        ] {
            for owned in [false, true] {
                let mut effects = (0, 0);
                dispatch_recording_stop(
                    phase,
                    owned,
                    &mut effects,
                    |effects| effects.0 += 1,
                    |effects| effects.1 += 1,
                );
                assert_eq!(
                    effects,
                    if phase == Phase::Idle && owned {
                        (1, 0)
                    } else {
                        (0, 1)
                    }
                );
            }
        }
    }

    #[test]
    fn forwarded_actions_wait_in_the_existing_queue_until_dispatch() {
        let expected = [
            DeepLinkAction::OpenSettings { page: None },
            DeepLinkAction::OpenEditor {
                project_path: "/tmp/forwarded-recording.cap".into(),
            },
        ];
        for action in &expected {
            submit_action(action.clone());
        }
        #[cfg(any(target_os = "macos", target_os = "windows"))]
        assert!(submit_reopen());
        for action in expected {
            assert_eq!(
                channel().1.try_recv().unwrap(),
                QueuedAction::DeepLink(action)
            );
        }
        #[cfg(any(target_os = "macos", target_os = "windows"))]
        assert_eq!(channel().1.try_recv().unwrap(), QueuedAction::Reopen);
        assert!(channel().1.is_empty());
    }

    #[test]
    fn private_reopen_is_not_a_public_deep_link_action() {
        for value in ["\"reopen\"", "{\"reopen\":{}}"] {
            let url = Url::parse_with_params("cap-desktop://action", &[("value", value)]).unwrap();
            assert!(DeepLinkAction::try_from(&url).is_err());
        }
    }

    // -- The Tauri parser's own tests (`deeplink_actions.rs:299-514`),
    // -- unchanged except for crate paths, so grammar drift fails loudly.

    #[test]
    fn parses_stop_recording_action_url() {
        let url = Url::parse("cap-desktop://action?value=%22stop_recording%22").unwrap();

        assert_eq!(
            DeepLinkAction::try_from(&url),
            Ok(DeepLinkAction::StopRecording)
        );
    }

    #[cfg(debug_assertions)]
    #[test]
    fn parses_open_camera_action_url() {
        let value = serde_json::json!({
            "open_camera": {
                "camera": { "DeviceID": "camera-1" }
            }
        })
        .to_string();
        let url = Url::parse_with_params("cap-desktop://action", &[("value", value)]).unwrap();

        assert_eq!(
            DeepLinkAction::try_from(&url),
            Ok(DeepLinkAction::OpenCamera {
                camera: DeviceOrModelID::DeviceID("camera-1".to_string())
            })
        );
    }

    #[cfg(debug_assertions)]
    #[test]
    fn parses_camera_preview_state_action_url() {
        let value = serde_json::json!({
            "set_camera_preview_state": {
                "state": {
                    "size": 400.0,
                    "shape": "full",
                    "mirrored": true,
                    "background_blur": "heavy"
                }
            }
        })
        .to_string();
        let url = Url::parse_with_params("cap-desktop://action", &[("value", value)]).unwrap();

        assert_eq!(
            DeepLinkAction::try_from(&url),
            Ok(DeepLinkAction::SetCameraPreviewState {
                state: CameraPreviewState {
                    size: 400.0,
                    shape: CameraPreviewShape::Full,
                    mirrored: true,
                    background_blur: cap_project::BackgroundBlurMode::Heavy,
                }
            })
        );
    }

    #[cfg(debug_assertions)]
    #[test]
    fn parses_pause_and_resume_action_urls() {
        let pause_url = Url::parse("cap-desktop://action?value=%22pause_recording%22").unwrap();
        let resume_url = Url::parse("cap-desktop://action?value=%22resume_recording%22").unwrap();

        assert_eq!(
            DeepLinkAction::try_from(&pause_url),
            Ok(DeepLinkAction::PauseRecording)
        );
        assert_eq!(
            DeepLinkAction::try_from(&resume_url),
            Ok(DeepLinkAction::ResumeRecording)
        );
    }

    #[cfg(debug_assertions)]
    #[test]
    fn parses_area_recording_action_url() {
        let value = serde_json::json!({
            "start_recording": {
                "capture_mode": {
                    "area": {
                        "screen": "Built-in Retina Display",
                        "x": 10.0,
                        "y": 20.0,
                        "width": 800.0,
                        "height": 600.0
                    }
                },
                "camera": { "DeviceID": "camera-1" },
                "mic_label": "microphone-1",
                "capture_system_audio": false,
                "mode": "instant"
            }
        })
        .to_string();
        let url = Url::parse_with_params("cap-desktop://action", &[("value", value)]).unwrap();

        assert_eq!(
            DeepLinkAction::try_from(&url),
            Ok(DeepLinkAction::StartRecording {
                capture_mode: CaptureMode::Area(Box::new(CaptureArea {
                    screen: "Built-in Retina Display".to_string(),
                    x: 10.0,
                    y: 20.0,
                    width: 800.0,
                    height: 600.0,
                })),
                camera: Some(DeviceOrModelID::DeviceID("camera-1".to_string())),
                mic_label: Some("microphone-1".to_string()),
                capture_system_audio: false,
                mode: cap_recording::RecordingMode::Instant,
            })
        );
    }

    #[cfg(debug_assertions)]
    #[test]
    fn parses_camera_only_recording_action_url() {
        let value = serde_json::json!({
            "start_recording": {
                "capture_mode": "camera_only",
                "camera": { "DeviceID": "camera-1" },
                "mic_label": "microphone-1",
                "capture_system_audio": false,
                "mode": "studio"
            }
        })
        .to_string();
        let url = Url::parse_with_params("cap-desktop://action", &[("value", value)]).unwrap();

        assert_eq!(
            DeepLinkAction::try_from(&url),
            Ok(DeepLinkAction::StartRecording {
                capture_mode: CaptureMode::CameraOnly,
                camera: Some(DeviceOrModelID::DeviceID("camera-1".to_string())),
                mic_label: Some("microphone-1".to_string()),
                capture_system_audio: false,
                mode: cap_recording::RecordingMode::Studio,
            })
        );
    }

    #[test]
    fn parses_start_recording_action_url() {
        let url = Url::parse(
            "cap-desktop://action?value=%7B%22start_recording%22%3A%7B%22capture_mode%22%3A%7B%22screen%22%3A%22Odyssey%20G93SC%22%7D%2C%22camera%22%3Anull%2C%22mic_label%22%3A%22Shure%20MV7%2B%22%2C%22capture_system_audio%22%3Atrue%2C%22mode%22%3A%22studio%22%7D%7D",
        )
        .unwrap();

        let Ok(DeepLinkAction::StartRecording {
            capture_mode,
            camera,
            mic_label,
            capture_system_audio,
            mode,
        }) = DeepLinkAction::try_from(&url)
        else {
            panic!("expected start recording action");
        };

        assert_eq!(
            capture_mode,
            CaptureMode::Screen("Odyssey G93SC".to_string())
        );
        assert_eq!(camera, None);
        assert_eq!(mic_label.as_deref(), Some("Shure MV7+"));
        assert!(capture_system_audio);
        assert_eq!(mode, cap_recording::RecordingMode::Studio);
    }

    #[test]
    fn parses_start_recording_action_with_camera_device_id() {
        let value = serde_json::json!({
            "start_recording": {
                "capture_mode": { "screen": "Odyssey G93SC" },
                "camera": { "DeviceID": "camera-1" },
                "mic_label": "Shure MV7+",
                "capture_system_audio": true,
                "mode": "studio"
            }
        })
        .to_string();
        let url = Url::parse_with_params("cap-desktop://action", &[("value", value)]).unwrap();

        let Ok(DeepLinkAction::StartRecording {
            camera,
            mic_label,
            capture_system_audio,
            ..
        }) = DeepLinkAction::try_from(&url)
        else {
            panic!("expected start recording action");
        };

        assert_eq!(
            camera,
            Some(DeviceOrModelID::DeviceID("camera-1".to_string()))
        );
        assert_eq!(mic_label.as_deref(), Some("Shure MV7+"));
        assert!(capture_system_audio);
    }

    #[test]
    fn rejects_non_action_host() {
        let url = Url::parse("cap-desktop://login?value=%22stop_recording%22").unwrap();

        assert_eq!(
            DeepLinkAction::try_from(&url),
            Err(ActionParseFromUrlError::NotAction)
        );
    }

    // -- This port's own coverage: the editor/settings shapes the Tauri file
    // -- never wrote tests for, and hostile input.

    #[test]
    fn parses_open_editor_and_open_settings_urls() {
        let editor = serde_json::json!({
            "open_editor": { "project_path": "/tmp/My Recording.cap" }
        })
        .to_string();
        let url = Url::parse_with_params("cap-desktop://action", &[("value", editor)]).unwrap();
        assert_eq!(
            DeepLinkAction::try_from(&url),
            Ok(DeepLinkAction::OpenEditor {
                project_path: PathBuf::from("/tmp/My Recording.cap"),
            })
        );

        let settings = serde_json::json!({ "open_settings": { "page": "hotkeys" } }).to_string();
        let url = Url::parse_with_params("cap-desktop://action", &[("value", settings)]).unwrap();
        assert_eq!(
            DeepLinkAction::try_from(&url),
            Ok(DeepLinkAction::OpenSettings {
                page: Some("hotkeys".to_string()),
            })
        );

        let settings = serde_json::json!({ "open_settings": { "page": null } }).to_string();
        let url = Url::parse_with_params("cap-desktop://action", &[("value", settings)]).unwrap();
        assert_eq!(
            DeepLinkAction::try_from(&url),
            Ok(DeepLinkAction::OpenSettings { page: None })
        );
    }

    /// Screenshot mode parses -- the type is `cap_recording::RecordingMode`,
    /// same as the Tauri enum -- and is refused later, at execution.
    #[test]
    fn parses_screenshot_mode() {
        let value = serde_json::json!({
            "start_recording": {
                "capture_mode": { "screen": "Display" },
                "camera": null,
                "mic_label": null,
                "capture_system_audio": false,
                "mode": "screenshot"
            }
        })
        .to_string();
        let url = Url::parse_with_params("cap-desktop://action", &[("value", value)]).unwrap();

        let Ok(DeepLinkAction::StartRecording { mode, .. }) = DeepLinkAction::try_from(&url) else {
            panic!("expected start recording action");
        };
        assert_eq!(mode, cap_recording::RecordingMode::Screenshot);
    }

    /// Malformed shapes are all `Err`, never a panic: this parser eats
    /// whatever the OS relays.
    #[test]
    fn rejects_malformed_urls() {
        // No authority at all -> no domain -> Invalid.
        let url = Url::parse("cap-desktop:action?value=%22stop_recording%22").unwrap();
        assert_eq!(
            DeepLinkAction::try_from(&url),
            Err(ActionParseFromUrlError::Invalid)
        );

        // Right host, no `value` parameter.
        let url = Url::parse("cap-desktop://action").unwrap();
        assert_eq!(
            DeepLinkAction::try_from(&url),
            Err(ActionParseFromUrlError::Invalid)
        );

        // `value` present but empty / not JSON / unknown action.
        for value in ["", "not json", "\"unknown_action\"", "{}", "[1,2,3]"] {
            let url = Url::parse_with_params("cap-desktop://action", &[("value", value)]).unwrap();
            assert!(
                matches!(
                    DeepLinkAction::try_from(&url),
                    Err(ActionParseFromUrlError::ParseFailed(_))
                ),
                "value {value:?} should fail to parse"
            );
        }

        // A known action with the wrong payload shape.
        let value = serde_json::json!({ "start_recording": { "capture_mode": 42 } }).to_string();
        let url = Url::parse_with_params("cap-desktop://action", &[("value", value)]).unwrap();
        assert!(matches!(
            DeepLinkAction::try_from(&url),
            Err(ActionParseFromUrlError::ParseFailed(_))
        ));
    }

    /// Any host other than exactly `action` is not ours -- the host is
    /// compared whole, never substring-matched, so `action.evil.example`
    /// cannot smuggle an action in.
    #[test]
    fn rejects_foreign_hosts() {
        for hostile in [
            "cap-desktop://evil.example?value=%22stop_recording%22",
            "cap-desktop://action.evil.example?value=%22stop_recording%22",
            "cap-desktop://xaction?value=%22stop_recording%22",
        ] {
            let url = Url::parse(hostile).unwrap();
            assert_eq!(
                DeepLinkAction::try_from(&url),
                Err(ActionParseFromUrlError::NotAction),
                "{hostile} must not parse as an action"
            );
        }
    }

    /// The Tauri parser discriminates on `Url::domain()`, which ignores the
    /// authority's userinfo and port -- so `user@action:8080` still reads as
    /// host `action`. Reproduced (and pinned) rather than tightened: nothing
    /// here ever *builds* a URL from these parts, which is where the
    /// port-injection class lives, and diverging would break URLs the
    /// shipping app accepts.
    #[test]
    fn authority_decorations_match_tauri() {
        for accepted in [
            "cap-desktop://action:8080?value=%22stop_recording%22",
            "cap-desktop://user@action?value=%22stop_recording%22",
        ] {
            let url = Url::parse(accepted).unwrap();
            assert_eq!(
                DeepLinkAction::try_from(&url),
                Ok(DeepLinkAction::StopRecording),
                "{accepted} parses on the Tauri grammar"
            );
        }
    }

    /// A nesting bomb is an `Err`, not a crash: the enum deserializer rejects
    /// the wrong shape immediately, and serde_json's own recursion limit
    /// backstops anything that gets deeper. Pinned so a hand-rolled parser
    /// can never regress this into a stack overflow.
    #[test]
    fn hostile_json_does_not_panic() {
        let bomb = format!("{}{}", "[".repeat(400), "]".repeat(400));
        let url = Url::parse_with_params("cap-desktop://action", &[("value", bomb)]).unwrap();
        assert!(matches!(
            DeepLinkAction::try_from(&url),
            Err(ActionParseFromUrlError::ParseFailed(_))
        ));

        let nul = "\"stop_recording\u{0}\"";
        let url = Url::parse_with_params("cap-desktop://action", &[("value", nul)]).unwrap();
        assert!(DeepLinkAction::try_from(&url).is_err());
    }

    /// The macOS `file://` branch: a local path becomes `OpenEditor`; a
    /// remote-host file URL does not convert to a path and is rejected.
    #[cfg(target_os = "macos")]
    #[test]
    fn file_urls_open_the_editor() {
        let url = Url::parse("file:///tmp/My%20Recording.cap").unwrap();
        assert_eq!(
            DeepLinkAction::try_from(&url),
            Ok(DeepLinkAction::OpenEditor {
                project_path: PathBuf::from("/tmp/My Recording.cap"),
            })
        );

        let url = Url::parse("file://evil.example/tmp/foo.cap").unwrap();
        assert_eq!(
            DeepLinkAction::try_from(&url),
            Err(ActionParseFromUrlError::Invalid)
        );
    }
}