dotfiles/docs/superpowers/specs/2026-05-02-flameshot-screenshot-design.md

Switch Screenshot Stack to Flameshot

Date: 2026-05-02 Status: Approved

Summary

Replace the bespoke screenshot pipeline (scripts/screenshot.sh + grim/slurp/wofi/notification flow) with Flameshot. Flameshot provides region select, on-canvas annotation, save, copy, and discard in a single integrated GUI — collapsing the current two-step "capture → notification → wofi → tool" flow into one.

Current Behaviour

Mod+Print runs ~/.local/bin/screenshot which is a symlink to scripts/screenshot.sh:

1. slurp | grim for region select + capture, save to ~/Pictures/screenshot-<unix-ts>.png.
2. wl-copy the file.
3. mako notification with thumbnail + "Actions" button (10 s timeout).
4. If "Actions" clicked, wofi menu offers: Annotate (swappy), Annotate (satty), Open in imv, Copy path, Delete.

Three keypresses or clicks to reach the annotator. The notification window steals focus for 10 seconds. Two annotators offered; both must be installed.

Target Behaviour

Mod+Print runs flameshot gui. The Flameshot toolbar appears overlaid on the screen with region selector + drawing tools (arrow, rectangle, blur, text, etc.) + Save/Copy/Discard buttons. Capture, edit, and dispatch are one continuous interaction. No notification, no wofi menu, no separate annotator.

Implementation

Packages

• Add to packages.txt: flameshot (extra repo, no AUR helper needed).
• Remove from packages.txt: none — swappy, satty, grim, slurp are kept (used by other tools or potentially useful standalone). Flameshot replaces only the orchestration script.

Files to delete

• scripts/screenshot.sh
• ~/.local/bin/screenshot (the symlink)
• install.sh line: ln -sf "$(pwd)/scripts/screenshot.sh" ~/.local/bin/screenshot

Niri keybind change

In niri/config.kdl, replace:

Mod+Print { spawn "screenshot"; }

with:

Mod+Print { spawn "flameshot" "gui"; }

Single keybind only — no additional shortcuts for full-screen / delayed / monitor modes. Those live inside the Flameshot toolbar already.

Flameshot configuration

The flameshot config is generated by install.sh, not tracked in the repo. The pattern mirrors how mako/config is handled today — Flameshot writes machine-local state back to the file at runtime (savePath, last folder, etc.), so committing the file would create churn or risk leaking user paths into the repo.

The generated file content:

[General]
disabledTrayIcon=true
showStartupLaunchMessage=false
showHelp=false
copyAndCloseAfterUpload=true
uiColor=#81a2be
contrastUiColor=#1d1f21
contrastOpacity=190

• disabledTrayIcon=true — no SNI icon (the user has no system tray on the bar).
• showStartupLaunchMessage=false — suppress first-run notification.
• showHelp=false — suppress on-canvas tooltip overlay every capture.
• copyAndCloseAfterUpload=true — auto-copy to clipboard when saved.
• uiColor / contrastUiColor — Tomorrow Night palette (@tn-blue and @tn-bg from theme/colors.css) so the toolbar matches the rest of the desktop.
• contrastOpacity=190 — Flameshot's standard mid-opacity backdrop dimming during capture.

Notably NOT included:

• savePath — Flameshot's INI format does not expand ~, so a hardcoded /home/alex/Pictures would break for any other user. On first save Flameshot will prompt for a destination; the user picks ~/Pictures and Flameshot remembers it locally (the resulting file gets written through the symlink back into the repo, but flameshot/flameshot.ini is gitignored — see below — so it stays local).

install.sh changes

• Remove: ln -sf "$(pwd)/scripts/screenshot.sh" ~/.local/bin/screenshot

• Add: A here-doc generator block (mirroring the mako pattern, lines 32-42) that writes ~/.config/flameshot/flameshot.ini if the file doesn't already exist:

  mkdir -p ~/.config/flameshot
  if [ ! -f ~/.config/flameshot/flameshot.ini ]; then
      cat > ~/.config/flameshot/flameshot.ini <<'INI'
  [General]
  disabledTrayIcon=true
  showStartupLaunchMessage=false
  showHelp=false
  copyAndCloseAfterUpload=true
  uiColor=#81a2be
  contrastUiColor=#1d1f21
  contrastOpacity=190
  INI
  fi
  

  The if [ ! -f ] guard prevents clobbering the user's saved preferences (savePath, last folder, etc.) on re-runs. This differs from the mako block (which always overwrites) — Flameshot's config accumulates user-chosen state, so we must not stomp it.

Files Touched

• packages.txt — add flameshot
• niri/config.kdl — change one keybind line
• install.sh — remove one symlink line, add the flameshot config generator
• scripts/screenshot.sh — deleted

Out of Scope

• Additional keybinds (full-screen, delayed, monitor) — Flameshot's toolbar already exposes these. One keybind is enough.
• Removing swappy / satty / imv / grim / slurp from packages — they're useful standalone and don't carry weight.
• Theming Flameshot beyond the two color values — Flameshot's UI is otherwise Qt-default and doesn't take much further customization.
• Setting savePath declaratively — the INI format does not support ~ expansion; let Flameshot's first-save prompt handle it.
• Adapting to portal limitations on Wayland — if Flameshot misbehaves under the xdg-desktop-portal-wlr backend, that's a Flameshot/portal issue to file upstream, not something this spec addresses.