docs: add interactive screenshot design spec

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-28 11:22:51 -07:00
parent 8a087d123f
commit 5639219d9f
1 changed files with 77 additions and 0 deletions
@@ -0,0 +1,77 @@
+# Interactive Screenshot Script Design
+
+**Date:** 2026-04-28
+**Status:** Approved
+
+## Summary
+
+Replace the current minimal screenshot script with an interactive post-capture flow: a mako notification confirms the capture and offers an "Actions" button; clicking it opens a wofi dmenu with five options. Dismissing the notification requires no further interaction.
+
+## Current Behaviour
+
+```bash
+FILE=~/Pictures/screenshot-$(date +%s).png
+grim -g "$(slurp)" "$FILE"
+wl-copy < "$FILE"
+```
+
+Captures a region, saves to `~/Pictures/`, copies to clipboard. No feedback, no post-capture options.
+
+## Flow
+
+```
+slurp (region select)
+  └─ cancelled (exit ≠ 0)? → exit silently
+grim → ~/Pictures/screenshot-<timestamp>.png
+wl-copy → copy image bytes to clipboard
+notify-send --wait
+  title:  "Screenshot captured"
+  body:   "Saved · Copied to clipboard"
+  icon:   $FILE (mako shows thumbnail)
+  action: "actions:Actions"
+  timeout: 10 000 ms
+  └─ dismissed / timed out → done
+  └─ "Actions" clicked → wofi --dmenu --prompt "Screenshot"
+      ├─ Annotate with swappy   (default, top)
+      ├─ Annotate with satty
+      ├─ Open in imv
+      ├─ Copy path
+      └─ Delete
+```
+
+## Actions
+
+| Choice | Command | Follow-up |
+|---|---|---|
+| Annotate with swappy | `swappy -f "$FILE" &` | swappy handles its own save |
+| Annotate with satty | `satty --filename "$FILE" &` | satty handles its own save |
+| Open in imv | `imv "$FILE" &` | none |
+| Copy path | `printf '%s' "$FILE" \| wl-copy` | notification: "Path copied" |
+| Delete | `rm "$FILE"` | notification: "Screenshot deleted" |
+
+Annotation tools are launched in background so the script does not block waiting for them.
+
+## Edge Cases
+
+- **slurp cancelled:** `grim` exits non-zero; script checks `$?` and exits cleanly with no notification or file.
+- **No selection made:** same as above — slurp exits non-zero if the user escapes.
+- **wofi dismissed (Escape):** no action taken; file and clipboard copy are preserved.
+- **Delete:** immediate, no undo. A confirmation notification fires so the user knows it happened.
+
+## Files Changed
+
+- `scripts/screenshot.sh` — rewrite
+- `packages.txt` — add `satty`, `swappy` (already installed manually)
+
+## Tools Used
+
+| Tool | Purpose |
+|---|---|
+| `grim` | screen capture |
+| `slurp` | region selection |
+| `wl-copy` | clipboard |
+| `notify-send` | notification (mako daemon) |
+| `wofi --dmenu` | action picker |
+| `swappy` | annotation (default) |
+| `satty` | annotation (alternative) |
+| `imv` | image viewer |