Make FlashPaste a faster overlay-capable agent surface

Constraint: Preserve the bash fallback and existing clipboard intent behavior while adding overlay checks and reducing daemon hot-path process work.

Rejected: Commit generated agent state or the local references checkout | They are runtime/reference artifacts, not project deliverables.

Rejected: Per-paste tmux, screenshot, xclip, and trigger-log fan-out | It keeps avoidable subprocess and filesystem work on the hot path.

Confidence: medium

Scope-risk: broad

Directive: Keep overlayd diagnostics structured and keep hot-path probes throttled or opt-in.

Tested: cargo fmt --manifest-path rs/Cargo.toml --all --check; RUSTC_WRAPPER= cargo clippy --manifest-path rs/Cargo.toml --workspace --offline -- -D warnings; RUSTC_WRAPPER= cargo test --manifest-path rs/Cargo.toml --workspace --offline; bash -n bin/flashpaste-doctor.sh bin/tmux-paste-dispatch.sh bin/flashpaste-screenshot-preload.sh install.sh bootstrap.sh packaging/build-deb.sh packaging/build-rpm.sh; git diff --cached --check; bash bin/flashpaste-doctor.sh

Not-tested: Live Wayland layer-shell draw on this non-Wayland shell; AGENTS-release-check still reports historical missing tags/releases for older v1.10-v1.27 history.

Author: NagyVikt

.github/workflows/release.yml

@@ -19,7 +19,7 @@ jobs:
       - name: Install build dependencies
         run: |
           sudo apt-get update -qq
-          sudo apt-get install -y dpkg-dev lintian libwayland-dev libx11-dev libdbus-1-dev pkg-config
+          sudo apt-get install -y dpkg-dev lintian libwayland-dev libx11-dev libdbus-1-dev pkg-config libcairo2-dev libglib2.0-dev libpango1.0-dev
 
       - name: Resolve version from tag
         id: ver
@@ -46,6 +46,9 @@ jobs:
       - name: Build Rust workspace
         run: cargo build --release --manifest-path rs/Cargo.toml
 
+      - name: Build overlay daemon
+        run: cargo build --release --manifest-path rs/Cargo.toml -p flashpaste-overlayd --features wayland
+
       - name: Build .deb
         run: VERSION=${{ steps.ver.outputs.v }} bash packaging/build-deb.sh
 

CHANGELOG.md

@@ -6,25 +6,23 @@ Release-tag policy: every `vX.Y` commit on `main` must be tagged and have a matc
 
 ## [Unreleased]
 
+## [1.32] - 2026-05-20
+
 ### Added
 
-- Unified `flashpaste` CLI wrapping the six binaries (`dispatch`, `trigger`, `shoot`, `doctor`, `trace`, `mcp`)
-- `flashpaste-shoot --ocr` and `--ocr-only` flags for portal screenshot capture
-- `flashpaste-shoot --annotate` for screenshot annotation
-- `flashpasted` auto-compresses staged screenshots on the inotify path
-- `flashpaste-common` image auto-compress module
-- Doctor + docs surface OCR / annotate / auto-compress to users
-- `docs/` tree (architecture, install, troubleshooting, FAQ, comparison, use-cases, glossary)
-- `llms.txt` (AI-crawler manifest per llmstxt.org)
-- `CITATION.cff`
-- Distribution packaging: AUR PKGBUILDs (stable + git), Homebrew tap formula, Nix flake
-- Project-health files: `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`, this `CHANGELOG.md`, issue + PR templates, `FUNDING.yml`
-- CI: shellcheck + markdownlint + link-check workflow
-- Architecture Decision Records under `docs/adr/`
-- Reproducible benchmark suite (`bin/flashpaste-bench.sh`, `make bench`)
-- `assets/og-image.svg` for social sharing
-- `assets/hero-flow-light.svg` light-mode variant
-- README badges, animated SVG hero, animated tier-comparison chart, Mermaid sequence diagram, AI-assistant TL;DR block, extended FAQ, alternatives comparison
+- `flashpaste-overlayd`, a Wayland screen-annotation daemon for agent-driven highlights, pointers, labels, and fade-out TTLs.
+- Three MCP overlay tools in `flashpaste-mcp`: `highlight_region`, `point_at`, and `clear_annotations`.
+- GNOME-compatible overlay fallback path for environments without layer-shell support.
+- Multi-monitor overlay support so annotations map to the visible output geometry instead of assuming a single screen.
+
+### Changed
+
+- `flashpaste-doctor` now runs 17 core checks, up from the previous 13, including overlay daemon, socket, compositor, and draw-path probes.
+
+### Notes
+
+- Compositor support matrix: wlroots compositors with layer-shell get the native layer-surface path; GNOME/Mutter uses the fallback path; other compositors should run `flashpaste-overlayd --probe` before relying on MCP annotations.
+- GNOME fallback caveat: annotations are still programmatic and click-through by design, but Mutter does not expose the same layer-shell semantics as wlroots, so placement and stacking should be treated as best-effort until the probe and quickstart workflow pass on the target desktop.
 
 ## [1.26] - 2026-05-19
 
@@ -172,7 +170,8 @@ Release-tag policy: every `vX.Y` commit on `main` must be tagged and have a matc
 
 Initial commit: sub-120 ms bash hot path for image-paste into GNOME Wayland TUIs.
 
-[Unreleased]: https://github.com/NagyVikt/flashpaste/compare/v1.19...HEAD
+[Unreleased]: https://github.com/NagyVikt/flashpaste/compare/v1.32...HEAD
+[1.32]: https://github.com/NagyVikt/flashpaste/compare/v1.26...v1.32
 [1.19]: https://github.com/NagyVikt/flashpaste/releases/tag/v1.19
 [1.18]: https://github.com/NagyVikt/flashpaste/releases/tag/v1.18
 [1.17]: https://github.com/NagyVikt/flashpaste/releases/tag/v1.17

CONTRIBUTING.md

@@ -11,7 +11,7 @@ FlashPaste is a clipboard glue tool for **GNOME Wayland + kitty + tmux**. Patche
 ```bash
 git clone https://github.com/NagyVikt/flashpaste.git
 cd flashpaste
-./bin/flashpaste-doctor.sh    # 13-probe pre-flight; touches nothing
+./bin/flashpaste-doctor.sh    # 17-check pre-flight; touches nothing
 ./install.sh                  # symlinks into ~/.local/bin/, drops user systemd units
 ```
 

Makefile

@@ -2,6 +2,7 @@
 #
 # Useful targets:
 #   make deb           build .deb package into dist/
+#   make rpm           build .rpm package into dist/
 #   make install       run install.sh
 #   make doctor        run environment check
 #   make uninstall     remove symlinks (best-effort)
@@ -12,11 +13,12 @@ REPO_ROOT := $(shell pwd)
 VERSION ?= $(shell git describe --tags --abbrev=0 2>/dev/null | sed 's/^v//')
 VERSION := $(if $(VERSION),$(VERSION),0.1.0)
 
-.PHONY: deb install doctor uninstall clean release-deb help bench bench-tier1 bench-tier3 bench-markdown
+.PHONY: deb rpm install doctor uninstall clean release-deb help bench bench-tier1 bench-tier3 bench-markdown
 
 help:
 	@echo "flashpaste — make targets:"
 	@echo "  make deb           build .deb (VERSION=$(VERSION))"
+	@echo "  make rpm           build .rpm (VERSION=$(VERSION))"
 	@echo "  make install       run install.sh (symlinks into ~/.local/bin)"
 	@echo "  make doctor        environment check"
 	@echo "  make uninstall     remove symlinks"
@@ -30,6 +32,9 @@ help:
 deb:
 	VERSION=$(VERSION) bash packaging/build-deb.sh
 
+rpm:
+	VERSION=$(VERSION) bash packaging/build-rpm.sh
+
 install:
 	bash install.sh
 
@@ -41,14 +46,14 @@ uninstall:
 	@for f in tmux-paste-dispatch.sh clipboard-set.sh clipboard-janitor.sh \
 	          get-clipboard-text.sh clip-pipeline-log.sh screenshot-to-clipboard \
 	          flashpaste-screenshot-preload.sh flashpaste-doctor.sh \
-	          flashpaste-trace.sh wl-paste; do \
+	          flashpaste-trace.sh wl-paste flashpaste-overlayd flashpaste-overlay; do \
 	  [ -L "$$HOME/.local/bin/$$f" ] && rm "$$HOME/.local/bin/$$f" && echo "  removed ~/.local/bin/$$f" || true; \
 	done
 	@for f in wl-clipboard.desktop wl-paste.desktop wl-copy.desktop; do \
 	  [ -L "$$HOME/.local/share/applications/$$f" ] && rm "$$HOME/.local/share/applications/$$f" && echo "  removed ~/.local/share/applications/$$f" || true; \
 	done
 	@[ -L "$$HOME/paste_image.sh" ] && rm "$$HOME/paste_image.sh" && echo "  removed ~/paste_image.sh" || true
-	@systemctl --user disable --now clipboard-janitor.service flashpaste-screenshot-watcher.path 2>/dev/null || true
+	@systemctl --user disable --now clipboard-janitor.service flashpaste-screenshot-watcher.path flashpaste-overlayd.service 2>/dev/null || true
 	@echo "uninstall done"
 
 clean:

README.md

@@ -13,6 +13,17 @@ The missing clipboard glue between **GNOME · kitty · tmux** and your terminal
 
 <img src="assets/hero-animated.svg" alt="Animated diagram: a screenshot leaves the PrtScr key, travels through a glowing pipe past the mutter, kitty, and tmux layers, and lands in a Claude Code terminal as an attached image in 15 milliseconds — visualizing how FlashPaste pastes screenshots into terminal LLM agents on GNOME Wayland" width="100%">
 
+<!--
+  overlay-demo.gif slot — see "Agent-driven screen annotation" section below
+  and `docs/overlay-quickstart.md#record-the-demo-gif`. The asset lives at
+  `assets/overlay-demo.gif` (≤5 MB, 10–15 s). Uncomment the <img> tag below
+  once the file is committed; until then the placeholder keeps the README
+  free of broken images.
+-->
+<!--
+<img src="assets/overlay-demo.gif" alt="Demo GIF: user pastes a screenshot into Claude Code, Claude replies 'the bug is in this function' and a red box appears around the relevant code in the user's editor, the user clicks straight to it — driven by flashpaste-mcp's highlight_region tool and flashpaste-overlayd" width="100%">
+-->
+
 <br>
 
 <!-- Badges, grouped: project · stack · ecosystem -->
@@ -130,22 +141,39 @@ FlashPaste is **MIT** — fork it, vendor it, ship it.
 ## flashpaste-mcp — agents get a first-class API
 
 <div align="center">
-<img src="assets/mcp-flow.svg" alt="Animated sequence diagram of flashpaste-mcp: a terminal LLM agent on the left (Claude Code, Codex CLI, Aider) sends four MCP tool calls — take_screenshot, read_clipboard, copy_text, paste_to_pane — along colored lanes to the flashpaste-mcp server on the right" width="100%">
+<img src="assets/mcp-flow.svg" alt="Animated sequence diagram of flashpaste-mcp: a terminal LLM agent on the left (Claude Code, Codex CLI, Aider) sends MCP tool calls including take_screenshot, read_clipboard, copy_text, paste_to_pane, highlight_region, point_at, and clear_annotations along colored lanes to the flashpaste-mcp server on the right" width="100%">
 </div>
 
-`flashpaste-mcp` is a drop-in [Model Context Protocol](https://modelcontextprotocol.io) server. Any MCP-aware client ([Claude Code](https://www.anthropic.com/claude-code), [Codex CLI](https://github.com/openai/codex), [Aider](https://github.com/Aider-AI/aider), [Continue](https://github.com/continuedev/continue), …) picks it up automatically and gets four tools:
+`flashpaste-mcp` is a drop-in [Model Context Protocol](https://modelcontextprotocol.io) server. Any MCP-aware client ([Claude Code](https://www.anthropic.com/claude-code), [Codex CLI](https://github.com/openai/codex), [Aider](https://github.com/Aider-AI/aider), [Continue](https://github.com/continuedev/continue), ...) picks it up automatically and gets clipboard, screenshot, paste, and screen annotation tools:
 
 | Tool | What it does |
 |---|---|
 | `take_screenshot` | Capture via `xdg-desktop-portal` → returns PNG bytes + MIME |
 | `read_clipboard` | Read the current Wayland selection (text or image) with MIME |
 | `copy_text` | Place text on the clipboard via the stable daemon owner |
 | `paste_to_pane` | Send a paste to a specific kitty/tmux pane by id, even unfocused |
+| `highlight_region` | Draw a temporary rectangle or circle highlight on the user's visible screen |
+| `point_at` | Draw a temporary pointer arrow toward a specific screen location |
+| `clear_annotations` | Clear active overlay highlights, pointers, and labels |
 
 Drop it in your client config — see [`docs/architecture.md`](docs/architecture.md#mcp).
 
 ---
 
+## Agent-driven screen annotation
+
+Once the agent can *see* your screen (via `take_screenshot`), the next obvious move is to let it *point at things*. `flashpaste-overlayd` is a tiny Rust daemon that paints temporary boxes, arrows, and labels directly on your Wayland screen, driven by three MCP tools that ship in the same `flashpaste-mcp` server — `highlight_region`, `point_at`, `clear_annotations`. Claude reads your screenshot, decides "the bug is in this function," draws a red box around it, and you click straight there. Annotations are click-through by default, fade out on a TTL, and never block your input.
+
+```jsonc
+// One MCP call from the agent → red box appears on screen for 4 seconds.
+{"name": "highlight_region",
+ "arguments": {"shape": "rect", "x": 412, "y": 318, "w": 280, "h": 96, "color": "#ff3b30", "label": "the bug is in this function", "ttl_ms": 4000}}
+```
+
+Setup, the GNOME caveat, and the recording recipe live in [`docs/overlay-quickstart.md`](docs/overlay-quickstart.md).
+
+---
+
 ## How to install FlashPaste on Linux
 
 ### One-line bootstrap (any distro)
@@ -160,7 +188,7 @@ Then wire up your dotfiles, reload, and verify:
 cat ~/.local/share/flashpaste/examples/tmux.conf.snippet  >> ~/.tmux.conf
 cat ~/.local/share/flashpaste/examples/kitty.conf.snippet >> ~/.config/kitty/kitty.conf
 tmux source-file ~/.tmux.conf      # then restart kitty
-flashpaste-doctor                  # 13 green checks = ready
+flashpaste-doctor                  # 17 core checks = ready
 ```
 
 <details>
@@ -290,7 +318,7 @@ Yes — see [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`AGENTS.md`](AGENTS.md). T
 - [`CHANGELOG.md`](CHANGELOG.md) — release history (Keep-a-Changelog).
 - [`AGENTS.md`](AGENTS.md) — contributor + AI-agent guide; release workflow lives here.
 - [`llms.txt`](llms.txt) — AI-crawler manifest ([llmstxt.org](https://llmstxt.org) standard).
-- [`flashpaste-mcp`](docs/architecture.md) — MCP server: `take_screenshot`, `read_clipboard`, `copy_text`, `paste_to_pane`.
+- [`flashpaste-mcp`](docs/architecture.md) — MCP server: `take_screenshot`, `read_clipboard`, `copy_text`, `paste_to_pane`, `highlight_region`, `point_at`, `clear_annotations`.
 
 MIT — see [LICENSE](LICENSE). Built by [@NagyVikt](https://github.com/NagyVikt).
 
@@ -313,7 +341,7 @@ If FlashPaste saved you a Wayland headache, a [GitHub star](https://github.com/N
   "@type": "SoftwareApplication",
   "name": "FlashPaste",
   "alternateName": ["flashpaste", "flash-paste"],
-  "description": "Sub-15 ms image-paste glue for terminal AI agents (Claude Code, Codex CLI, Aider, llm) on GNOME Wayland. Works around mutter's surfaceless-client clipboard refusal, kitty's map ctrl+v interception, and tmux's bind -n C-v recursion via three progressive performance tiers.",
+  "description": "Sub-15 ms image-paste glue and agent overlay for terminal AI agents (Claude Code, Codex CLI, Aider, llm) on GNOME Wayland. Works around mutter's surfaceless-client clipboard refusal, kitty's map ctrl+v interception, and tmux's bind -n C-v recursion via three progressive performance tiers, then lets MCP clients annotate the visible screen with highlight_region, point_at, and clear_annotations.",
   "url": "https://github.com/NagyVikt/flashpaste",
   "codeRepository": "https://github.com/NagyVikt/flashpaste",
   "downloadUrl": "https://github.com/NagyVikt/flashpaste/releases/latest",
@@ -323,6 +351,14 @@ If FlashPaste saved you a Wayland headache, a [GitHub star](https://github.com/N
   "license": "https://spdx.org/licenses/MIT.html",
   "programmingLanguage": ["Rust", "Bash"],
   "softwareRequirements": ["kitty", "tmux", "wl-clipboard", "xclip", "ydotool"],
+  "featureList": [
+    "Sub-15 ms screenshot paste into terminal LLM agents on GNOME Wayland",
+    "MCP server for screenshot capture, clipboard reads, text copy, and pane paste",
+    "Agent overlay for screen annotation on visible Linux UI regions",
+    "highlight_region draws temporary rectangles or circles on the user's screen",
+    "point_at draws temporary screen pointer arrows for buttons, panels, and app regions",
+    "clear_annotations removes active overlay highlights, pointers, and labels"
+  ],
   "offers": { "@type": "Offer", "price": "0", "priceCurrency": "USD" },
   "author": {
     "@type": "Person",
@@ -334,6 +370,8 @@ If FlashPaste saved you a Wayland headache, a [GitHub star](https://github.com/N
     "claude code", "codex cli", "aider", "llm cli",
     "image paste linux", "screenshot paste terminal",
     "mcp server", "model context protocol",
+    "screen annotation", "agent overlay", "mcp screen pointer", "linux ai overlay",
+    "highlight_region", "point_at", "clear_annotations",
     "terminal ai", "llm agent", "wayland clipboard fix",
     "paste screenshot claude code linux",
     "ubuntu 24.04 wayland clipboard bug"
@@ -404,7 +442,7 @@ If FlashPaste saved you a Wayland headache, a [GitHub star](https://github.com/N
       "name": "Does FlashPaste include an MCP (Model Context Protocol) server?",
       "acceptedAnswer": {
         "@type": "Answer",
-        "text": "Yes. flashpaste-mcp is a drop-in MCP server that any MCP-aware client (Claude Code, Codex CLI, Aider, Continue) picks up automatically. It exposes four tools: take_screenshot (capture via xdg-desktop-portal), read_clipboard (current Wayland selection with MIME), copy_text (place text on the clipboard via the daemon owner), and paste_to_pane (send a paste to a specific kitty or tmux pane by id, even when unfocused)."
+        "text": "Yes. flashpaste-mcp is a drop-in MCP server that any MCP-aware client (Claude Code, Codex CLI, Aider, Continue) picks up automatically. It exposes tools for take_screenshot (capture via xdg-desktop-portal), read_clipboard (current Wayland selection with MIME), copy_text (place text on the clipboard via the daemon owner), paste_to_pane (send a paste to a specific kitty or tmux pane by id, even when unfocused), and overlay screen annotation through highlight_region, point_at, and clear_annotations."
       }
     }
   ]

THIRD_PARTY.md

@@ -0,0 +1,48 @@
+# Third-Party Notices
+
+This file records third-party projects directly referenced by the FlashPaste
+overlay work. FlashPaste itself is MIT licensed; see [`LICENSE`](LICENSE).
+
+## Runtime Dependencies
+
+### smithay-client-toolkit
+
+- Project: [Smithay client-toolkit](https://github.com/Smithay/client-toolkit)
+- Use: Wayland client and layer-shell plumbing for `flashpaste-overlayd`.
+- License: MIT.
+- Authors credited by the crate metadata: Elinor Berger, i509VCB, and Ashley
+  Wulber. The license text in the crate also carries Victor Berger's copyright.
+
+### cairo-rs, cairo-sys-rs, and pangocairo
+
+- Project: [gtk-rs core bindings](https://github.com/gtk-rs/gtk-rs-core)
+- Use: Rust bindings used by the optional overlay renderer.
+- License: MIT.
+- Authors credited by the crate metadata: The gtk-rs Project Developers.
+
+### Cairo graphics library
+
+- Project: [Cairo](https://www.cairographics.org/)
+- Use: Underlying 2D graphics library used through the Rust Cairo bindings.
+- License: LGPL-2.1 or MPL-1.1, at the user's option.
+- Credit: Cairo authors and contributors.
+
+## Reference Projects
+
+### Gromit-MPX
+
+- Project: [Gromit-MPX](https://github.com/bk138/gromit-mpx)
+- Use: Reference for mature human-driven screen annotation behavior.
+- License: GPL-2.0.
+- Credit: Simon Budig, Christian Beier, Barak A. Pearlmutter, and the
+  Gromit-MPX contributors listed in `references/gromit-mpx/AUTHORS`.
+- Note: FlashPaste does not copy or vendor Gromit-MPX code.
+
+### wayscriber
+
+- Project: [wayscriber](https://github.com/devmobasa/wayscriber)
+- Use: Reference for Wayland annotation UX, Smithay client-toolkit usage, Cairo
+  rendering, and compositor-specific behavior.
+- License: MIT.
+- Credit: devmobasa and wayscriber contributors.
+- Note: FlashPaste does not copy or vendor wayscriber code.