Add freeze-frame annotate via optional satty/swappy

After grim+slurp, satty (preferred) or swappy freezes the captured
frame for arrows/text/rect. New `breadshot annotate` / --annotate
and bread.command.shot.annotate. Missing tools warn and fall back
to the existing capture path. listen still honors region.

src/capture.rs

@@ -44,11 +44,35 @@ pub struct Overrides {
     pub clipboard_only: bool,
     pub silent: bool,
     pub freeze: bool,
+    pub annotate: bool,
     pub output_dir: Option<PathBuf>,
     pub filename: Option<String>,
 }
 
-pub fn run(mode: &Mode, config: &Config, overrides: Overrides) -> Result<()> {
+/// What a successful capture left behind. `path` is `None` when the user
+/// asked for clipboard-only, cancelled the annotator without saving, or
+/// the save file was never written.
+pub struct CaptureOutcome {
+    pub clipboard: bool,
+    pub path: Option<PathBuf>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum Annotator {
+    Satty,
+    Swappy,
+}
+
+impl Annotator {
+    fn name(self) -> &'static str {
+        match self {
+            Self::Satty => "satty",
+            Self::Swappy => "swappy",
+        }
+    }
+}
+
+pub fn run(mode: &Mode, config: &Config, overrides: Overrides) -> Result<CaptureOutcome> {
     check_deps()?;
 
     let save_dir = overrides.output_dir.as_ref().unwrap_or(&config.save_dir);
@@ -63,39 +87,61 @@ pub fn run(mode: &Mode, config: &Config, overrides: Overrides) -> Result<()> {
     let silent = overrides.silent || config.silent;
     let freeze = overrides.freeze || config.freeze;
     let clipboard_only = overrides.clipboard_only;
+    let annotator = resolve_annotator(overrides.annotate || config.annotate);
 
-    let _freeze_guard = if freeze {
-        FreezeGuard::try_spawn()
-            .map_err(|e| tracing::warn!("freeze: {e}"))
-            .ok()
-    } else {
-        None
+    // Capture under the optional hyprpicker freeze, then drop it before
+    // the annotator window appears so it can take the frozen frame.
+    let captured_png = {
+        let _freeze_guard = if freeze {
+            FreezeGuard::try_spawn()
+                .map_err(|e| tracing::warn!("freeze: {e}"))
+                .ok()
+        } else {
+            None
+        };
+
+        let geometry = geometry_for_mode(mode)?;
+        tracing::debug!("geometry: {geometry}");
+
+        if annotator.is_some() {
+            Some(grim_png(&geometry)?)
+        } else if clipboard_only {
+            copy_only(&geometry)?;
+            None
+        } else {
+            std::fs::create_dir_all(save_dir)
+                .with_context(|| format!("creating {}", save_dir.display()))?;
+            save_and_copy(&geometry, &save_path)?;
+            None
+        }
     };
 
-    let geometry = geometry_for_mode(mode)?;
-    tracing::debug!("geometry: {geometry}");
-
-    if clipboard_only {
-        copy_only(&geometry)?;
-    } else {
-        std::fs::create_dir_all(save_dir)
-            .with_context(|| format!("creating {}", save_dir.display()))?;
-        save_and_copy(&geometry, &save_path)?;
+    if let (Some(tool), Some(png)) = (annotator, captured_png) {
+        if !clipboard_only {
+            std::fs::create_dir_all(save_dir)
+                .with_context(|| format!("creating {}", save_dir.display()))?;
+        }
+        run_annotator(
+            tool,
+            &png,
+            (!clipboard_only).then_some(save_path.as_path()),
+            silent,
+        )?;
     }
 
     // Both capture paths copy the PNG to the clipboard. `path` is null
-    // when the user asked for clipboard-only (no file on disk).
-    emit_captured(
-        mode,
-        true,
-        if clipboard_only {
-            None
-        } else {
-            Some(save_path.as_path())
-        },
-    );
+    // when the user asked for clipboard-only (no file on disk) or the
+    // annotator exited without writing the save file.
+    let path = if clipboard_only || !save_path.exists() {
+        None
+    } else {
+        Some(save_path.as_path())
+    };
 
-    if !silent {
+    emit_captured(mode, true, path);
+
+    // The annotator owns its own copy/save notifications.
+    if !silent && annotator.is_none() {
         let msg = if clipboard_only {
             "Copied to clipboard".to_string()
         } else {
@@ -104,7 +150,10 @@ pub fn run(mode: &Mode, config: &Config, overrides: Overrides) -> Result<()> {
         send_notification("Screenshot", &msg, config.notif_timeout, &save_path);
     }
 
-    Ok(())
+    Ok(CaptureOutcome {
+        clipboard: true,
+        path: path.map(Path::to_path_buf),
+    })
 }
 
 // --- geometry ---
@@ -263,6 +312,103 @@ fn trim_geometry(geometry: &str) -> Result<String> {
 
 // --- capture ---
 
+fn grim_png(geometry: &str) -> Result<Vec<u8>> {
+    let out = Command::new("grim")
+        .args(["-g", geometry, "-"])
+        .output()
+        .context("running grim")?;
+    if !out.status.success() {
+        bail!("grim exited with {}", out.status);
+    }
+    Ok(out.stdout)
+}
+
+fn resolve_annotator(requested: bool) -> Option<Annotator> {
+    if !requested {
+        return None;
+    }
+    match find_annotator() {
+        Some(tool) => Some(tool),
+        None => {
+            eprintln!("breadshot: satty or swappy not found; capturing without annotation");
+            eprintln!(
+                "install satty (preferred) or swappy to freeze the frame and annotate (arrows/text/rect)"
+            );
+            tracing::warn!("annotate requested but satty/swappy missing");
+            None
+        }
+    }
+}
+
+fn find_annotator() -> Option<Annotator> {
+    if in_path("satty") {
+        Some(Annotator::Satty)
+    } else if in_path("swappy") {
+        Some(Annotator::Swappy)
+    } else {
+        None
+    }
+}
+
+fn annotator_args(tool: Annotator, save_path: Option<&Path>, silent: bool) -> Vec<String> {
+    match tool {
+        Annotator::Satty => {
+            let mut args = vec![
+                "--filename".into(),
+                "-".into(),
+                "--fullscreen".into(),
+                "--copy-command".into(),
+                "wl-copy".into(),
+            ];
+            if let Some(path) = save_path {
+                args.push("--output-filename".into());
+                args.push(path.to_string_lossy().into_owned());
+                args.push("--save-after-copy".into());
+            }
+            if silent {
+                args.push("--disable-notifications".into());
+            }
+            // Last so a value-taking satty does not swallow the next flag.
+            args.push("--early-exit".into());
+            args
+        }
+        Annotator::Swappy => {
+            let mut args = vec!["-f".into(), "-".into()];
+            if let Some(path) = save_path {
+                args.push("-o".into());
+                args.push(path.to_string_lossy().into_owned());
+            }
+            args
+        }
+    }
+}
+
+fn run_annotator(
+    tool: Annotator,
+    png: &[u8],
+    save_path: Option<&Path>,
+    silent: bool,
+) -> Result<()> {
+    let mut child = Command::new(tool.name())
+        .args(annotator_args(tool, save_path, silent))
+        .stdin(Stdio::piped())
+        .spawn()
+        .with_context(|| format!("spawning {}", tool.name()))?;
+
+    child
+        .stdin
+        .take()
+        .context("annotator stdin")?
+        .write_all(png)
+        .context("piping screenshot to annotator")?;
+
+    let status = child.wait().context("waiting for annotator")?;
+    if !status.success() {
+        bail!("{} exited with {status}", tool.name());
+    }
+    Ok(())
+}
+
 fn copy_only(geometry: &str) -> Result<()> {
     let mut grim = Command::new("grim")
         .args(["-g", geometry, "-"])
@@ -464,4 +610,57 @@ mod tests {
         assert_eq!(v["clipboard"], true);
         assert_eq!(v["path"], "/tmp/shot.png");
     }
+
+    #[test]
+    fn satty_args_fullscreen_copy_and_early_exit() {
+        let args = annotator_args(Annotator::Satty, None, false);
+        assert_eq!(
+            args,
+            [
+                "--filename",
+                "-",
+                "--fullscreen",
+                "--copy-command",
+                "wl-copy",
+                "--early-exit"
+            ]
+        );
+    }
+
+    #[test]
+    fn satty_args_save_path_and_silent() {
+        let path = Path::new("/tmp/shot.png");
+        let args = annotator_args(Annotator::Satty, Some(path), true);
+        assert_eq!(
+            args,
+            [
+                "--filename",
+                "-",
+                "--fullscreen",
+                "--copy-command",
+                "wl-copy",
+                "--output-filename",
+                "/tmp/shot.png",
+                "--save-after-copy",
+                "--disable-notifications",
+                "--early-exit"
+            ]
+        );
+    }
+
+    #[test]
+    fn swappy_args_stdin_and_optional_output() {
+        assert_eq!(annotator_args(Annotator::Swappy, None, true), ["-f", "-"]);
+        let path = Path::new("/tmp/shot.png");
+        assert_eq!(
+            annotator_args(Annotator::Swappy, Some(path), false),
+            ["-f", "-", "-o", "/tmp/shot.png"]
+        );
+    }
+
+    #[test]
+    fn annotator_prefers_satty_name() {
+        assert_eq!(Annotator::Satty.name(), "satty");
+        assert_eq!(Annotator::Swappy.name(), "swappy");
+    }
 }

src/config.rs

@@ -8,6 +8,8 @@ pub struct Config {
     pub save_dir: PathBuf,
     pub silent: bool,
     pub freeze: bool,
+    /// Open satty/swappy after capture to annotate the frozen frame.
+    pub annotate: bool,
     pub notif_timeout: u32,
     pub date_format: String,
 }
@@ -20,6 +22,7 @@ impl Default for Config {
                 .join("Screenshots"),
             silent: false,
             freeze: false,
+            annotate: false,
             notif_timeout: 5000,
             date_format: "%Y-%m-%d-%H%M%S".to_string(),
         }
@@ -36,10 +39,10 @@ impl Config {
             tracing::debug!("no config at {}, using defaults", path.display());
             return Ok(Self::default());
         }
-        let content = std::fs::read_to_string(path)
-            .with_context(|| format!("reading {}", path.display()))?;
-        let mut config: Self = toml::from_str(&content)
-            .with_context(|| format!("parsing {}", path.display()))?;
+        let content =
+            std::fs::read_to_string(path).with_context(|| format!("reading {}", path.display()))?;
+        let mut config: Self =
+            toml::from_str(&content).with_context(|| format!("parsing {}", path.display()))?;
         config.save_dir = expand_tilde(config.save_dir);
         Ok(config)
     }

src/listen.rs

@@ -6,7 +6,7 @@
 use anyhow::Result;
 use bread_utils::bread_client::{BreadClient, BreadEvent};
 
-use crate::capture::{self, Mode, Overrides, APP_ID};
+use crate::capture::{self, CaptureOutcome, Mode, Overrides, APP_ID};
 use crate::config::Config;
 
 /// Subscribe to `bread.command.shot.**` and block until the process is killed.
@@ -30,17 +30,19 @@ pub fn run(config: &Config) -> Result<()> {
     }
 }
 
-/// Reacts to `bread.command.shot.*` verbs. Only `region` is honored today —
-/// other verbs are ignored, not stubbed as no-ops that pretend to succeed.
+/// Reacts to `bread.command.shot.*` verbs. Only `region` and `annotate` are
+/// honored — other verbs are ignored, not stubbed as no-ops that pretend
+/// to succeed.
 ///
-/// Emits `bread.shot.region.done` / `.failed` per the confirmation convention
-/// in bread's Documentation.md.
+/// Emits `bread.shot.<verb>.done` / `.failed` per the confirmation
+/// convention in bread's Documentation.md.
 fn handle_command(event: &BreadEvent, config: &Config) {
     let Some(verb) = command_verb(&event.event) else {
         return;
     };
     match verb {
         "region" => handle_region(config),
+        "annotate" => handle_annotate(config),
         other => {
             tracing::debug!("ignoring unrecognized command verb '{other}'");
         }
@@ -57,16 +59,43 @@ fn handle_region(config: &Config) {
             clipboard_only: true,
             silent: false,
             freeze: false,
+            annotate: false,
             output_dir: None,
             filename: None,
         },
     );
     let client = BreadClient::connect(APP_ID);
     match result {
-        Ok(()) => client.emit("bread.shot.region.done", region_done_payload()),
+        Ok(_) => client.emit("bread.shot.region.done", region_done_payload()),
         Err(e) => {
             tracing::warn!("bread.command.shot.region failed: {e}");
-            client.emit("bread.shot.region.failed", region_failed_payload(&e));
+            client.emit("bread.shot.region.failed", command_failed_payload(&e));
+        }
+    }
+}
+
+fn handle_annotate(config: &Config) {
+    // Interactive: satty/swappy get a default save path so the user can
+    // write the annotated frame. If the annotator is missing, this falls
+    // back to a normal region save (with a warning on stderr).
+    let result = capture::run(
+        &Mode::Region,
+        config,
+        Overrides {
+            clipboard_only: false,
+            silent: false,
+            freeze: false,
+            annotate: true,
+            output_dir: None,
+            filename: None,
+        },
+    );
+    let client = BreadClient::connect(APP_ID);
+    match result {
+        Ok(outcome) => client.emit("bread.shot.annotate.done", annotate_done_payload(&outcome)),
+        Err(e) => {
+            tracing::warn!("bread.command.shot.annotate failed: {e}");
+            client.emit("bread.shot.annotate.failed", command_failed_payload(&e));
         }
     }
 }
@@ -79,10 +108,17 @@ fn region_done_payload() -> serde_json::Value {
     serde_json::json!({ "clipboard": true, "path": serde_json::Value::Null })
 }
 
-fn region_failed_payload(error: &impl ToString) -> serde_json::Value {
+fn command_failed_payload(error: &impl ToString) -> serde_json::Value {
     serde_json::json!({ "error": error.to_string() })
 }
 
+fn annotate_done_payload(outcome: &CaptureOutcome) -> serde_json::Value {
+    serde_json::json!({
+        "clipboard": outcome.clipboard,
+        "path": outcome.path.as_ref().map(|p| p.to_string_lossy().into_owned()),
+    })
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -90,6 +126,10 @@ mod tests {
     #[test]
     fn command_verb_strips_shot_prefix() {
         assert_eq!(command_verb("bread.command.shot.region"), Some("region"));
+        assert_eq!(
+            command_verb("bread.command.shot.annotate"),
+            Some("annotate")
+        );
         assert_eq!(command_verb("bread.command.shot.window"), Some("window"));
         assert_eq!(command_verb("bread.command.clip.clear"), None);
         assert_eq!(command_verb("bread.shot.captured"), None);
@@ -103,8 +143,28 @@ mod tests {
     }
 
     #[test]
-    fn region_failed_payload_includes_error() {
-        let v = region_failed_payload(&"selection cancelled");
+    fn command_failed_payload_includes_error() {
+        let v = command_failed_payload(&"selection cancelled");
         assert_eq!(v["error"], "selection cancelled");
     }
+
+    #[test]
+    fn annotate_done_payload_includes_saved_path() {
+        let v = annotate_done_payload(&CaptureOutcome {
+            clipboard: true,
+            path: Some(std::path::PathBuf::from("/tmp/shot.png")),
+        });
+        assert_eq!(v["clipboard"], true);
+        assert_eq!(v["path"], "/tmp/shot.png");
+    }
+
+    #[test]
+    fn annotate_done_payload_null_path_when_unsaved() {
+        let v = annotate_done_payload(&CaptureOutcome {
+            clipboard: true,
+            path: None,
+        });
+        assert_eq!(v["clipboard"], true);
+        assert!(v["path"].is_null());
+    }
 }

src/main.rs

@@ -40,6 +40,10 @@ struct CaptureOpts {
     #[arg(long, short = 'z')]
     freeze: bool,
 
+    /// Freeze the captured frame and annotate (requires satty or swappy)
+    #[arg(long, short = 'a')]
+    annotate: bool,
+
     /// Override save directory from config
     #[arg(long, short = 'o', value_name = "DIR")]
     output_dir: Option<PathBuf>,
@@ -63,7 +67,9 @@ enum Command {
     /// Capture the active monitor
     #[command(name = "active-output")]
     ActiveOutput(CaptureOpts),
-    /// Subscribe to bread.command.shot.** and honor region captures
+    /// Capture a region, freeze the frame, and annotate
+    Annotate(CaptureOpts),
+    /// Subscribe to bread.command.shot.** and honor region/annotate captures
     Listen,
 }
 
@@ -75,6 +81,10 @@ impl Command {
             Self::Output(opts) => Some((Mode::Output, opts)),
             Self::ActiveWindow(opts) => Some((Mode::ActiveWindow, opts)),
             Self::ActiveOutput(opts) => Some((Mode::ActiveOutput, opts)),
+            Self::Annotate(mut opts) => {
+                opts.annotate = true;
+                Some((Mode::Region, opts))
+            }
             Self::Listen => None,
         }
     }
@@ -104,8 +114,10 @@ fn main() -> Result<()> {
             clipboard_only: opts.clipboard_only,
             silent: opts.silent,
             freeze: opts.freeze,
+            annotate: opts.annotate,
             output_dir: opts.output_dir,
             filename: opts.filename,
         },
-    )
+    )?;
+    Ok(())
 }