Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

feat(appshot): put every screenshot on the clipboard in all formats, on every OS

rubenluetke10-beepf3d35fcc876c
diff --git a/docs/appshots.md b/docs/appshots.md
index 675ca8bbf8..fb068c70fc 100644
--- a/docs/appshots.md
+++ b/docs/appshots.md
@@ -19,6 +19,28 @@ overlays (the mascot, the bar) take the focus when you click them, so the
capture looks past them to the app window underneath (BUG-228); with no app
window there, it takes the whole screen instead.
+## Paste it anywhere
+
+Every appshot taken with a shortcut or a **Try it** button also goes on the
+system clipboard, so Ctrl+V (Cmd+V on a Mac) pastes it straight into a chat,
+a mail, a document or an image editor. It is the finished picture, markings
+included, at full resolution (the lossless copy, not the smaller picture the
+assistant gets). Looks the assistant takes on its own, or a spoken "what do
+you see?", never replace what is on the clipboard. **Copy to clipboard** on
+the Appshots page (`[appshot].copy_to_clipboard`) turns it off.
+
+The clipboard holds the same picture in several formats at once, because
+every app asks for a different one (`jarvis/platform/clipboard_image.py`):
+
+| OS | Formats | Who reads what |
+|---|---|---|
+| Windows | `PNG` (registered format, offered first) + `CF_DIB`; Windows adds `CF_BITMAP` and `CF_DIBV5` itself | Browsers, Electron chat apps and Office take the lossless PNG with its transparency; classic Win32 apps (Paint and older tools) take the bitmap, where transparent parts are laid on white instead of turning black |
+| macOS | `public.png` + `public.tiff` on the general pasteboard, set through the built-in JavaScript for Automation bridge (`osascript -l JavaScript`); AppleScript sets the PNG alone if that bridge fails | Modern apps read PNG; TIFF is the pasteboard's native image type that older Cocoa apps read |
+| Linux | `image/png` through `wl-copy` (Wayland) or `xclip` (X11) | Every X11 and Wayland toolkit reads `image/png`. Without either tool nothing is copied and the log names the package to install |
+| Headless | — | No clipboard; nothing is attempted |
+
+Jarvis X screenshots (`[jarvisx].copy_to_clipboard`) use the same code.
+
## Selecting an area
The area picker is a short-lived PySide6 process (`python -m
@@ -366,6 +388,7 @@ original any-order behaviour.
| `effect` | `true` | Flash and corner thumbnail |
| `card_seconds` | `6` | How long the corner card rests, 0–600 seconds; `0` = until closed |
| `library` | `true` | Keep every appshot and saved edit in the gallery (`<data dir>/appshots/`, newest 500) |
+| `copy_to_clipboard` | `true` | Put shortcut and button appshots on the clipboard (see [Paste it anywhere](#paste-it-anywhere)) |
## Operating systems
diff --git a/docs/os-parity.md b/docs/os-parity.md
index 49c8a2813d..f45744047a 100644
--- a/docs/os-parity.md
+++ b/docs/os-parity.md
@@ -1,5 +1,18 @@
# OS Feature Parity — macOS / Linux Gap Register
+## Screenshots paste anywhere (2026-10-05, T2)
+
+Appshots taken by shortcut or button and Jarvis X screenshots go on the
+clipboard in several formats at once (`jarvis/platform/clipboard_image.py`):
+Windows `PNG` + `CF_DIB` (transparency laid on white in the bitmap), macOS
+`public.png` + `public.tiff` through `osascript -l JavaScript` with an
+AppleScript PNG-only fallback, Linux `image/png` through `wl-copy` or `xclip`.
+The Linux copy commands (images and text) no longer wait on a pipe that the
+forked clipboard owner keeps open, which used to report every copy as failed
+after the five-second timeout. Verified live on Windows (PNG, DIB and the
+derived bitmap formats read back); macOS and Linux are covered by unit tests
+of the exact commands, not by a real pasteboard or X11/Wayland session.
+
## AppShot colour fidelity: HDR and wide gamut (2026-10-05, T3)
Screenshots and recordings decide at capture time, per monitor, whether the
@@ -796,7 +809,7 @@ implementations, not stubs.
|---|---|
| Computer-Use / desktop actions (click, type, hotkey, scroll, drag, windows, apps, screenshots, UI trees) | Full per-OS backends (Win32/UIA, Quartz/AX, xdotool/AT-SPI); honest degradation on Wayland/headless/missing TCC grants |
| On-demand Screen Context | One-shot capture is wired into the production brain on Windows, macOS, and Linux/X11; UIA/AX/AT-SPI text is source-filtered, the indicator precedes capture, and Wayland/headless/missing grants refuse honestly |
-| Appshots (front-window capture on a shortcut, button or request) | Capture, privacy and delivery are OS-neutral (Screen Context engine, `jarvis/appshot`). The two-sided shortcuts (both Alt, both Shift, both Ctrl) read key state per OS: Windows `GetAsyncKeyState`, macOS `CGEventSourceKeyState` (Input Monitoring grant), Linux/X11 `XQueryKeymap`; Wayland/headless report it unavailable on the Appshots page. The flash and the area picker (both Shift keys, drag a rectangle, then mark it up with its toolbar) are PySide6 overlays where one can run; the markings are burnt into the capture with Pillow on every OS (`jarvis/appshot/markup.py`); Wayland/headless report the area picker unavailable. The appshot editor is web code and behaves the same everywhere; its Copy writes the PNG natively (`jarvis/platform/clipboard_image.py`): Windows `CF_DIB` + the registered PNG format, macOS `osascript` as `«class PNGf»`, Linux `wl-copy` or `xclip`, and with neither the browser clipboard. Save goes to `~/Downloads` on every OS. Verified live on Windows only; see `docs/appshots.md` |
+| Appshots (front-window capture on a shortcut, button or request) | Capture, privacy and delivery are OS-neutral (Screen Context engine, `jarvis/appshot`). The two-sided shortcuts (both Alt, both Shift, both Ctrl) read key state per OS: Windows `GetAsyncKeyState`, macOS `CGEventSourceKeyState` (Input Monitoring grant), Linux/X11 `XQueryKeymap`; Wayland/headless report it unavailable on the Appshots page. The flash and the area picker (both Shift keys, drag a rectangle, then mark it up with its toolbar) are PySide6 overlays where one can run; the markings are burnt into the capture with Pillow on every OS (`jarvis/appshot/markup.py`); Wayland/headless report the area picker unavailable. The appshot editor is web code and behaves the same everywhere; its Copy, and every shortcut or button appshot, writes the picture natively in several formats (`jarvis/platform/clipboard_image.py`): Windows the registered PNG format + `CF_DIB`, macOS `public.png` + `public.tiff` via `osascript -l JavaScript`, Linux `wl-copy` or `xclip`; the editor falls back to the browser clipboard without them. Save goes to `~/Downloads` on every OS. Verified live on Windows only; see `docs/appshots.md` |
| Voice / audio (capture, playback, VAD, wake, STT, TTS, realtime) | Clean; headless disables voice honestly; WASAPI logic is inert-by-data off Windows |
| Core (launcher, config, keyring, restart, autostart, tray, elevation, paths) | Clean; per-OS autostart (Registry / LaunchAgent / XDG `.desktop`), keyring falls back to a 0600 file on headless hosts |
| Data / agents (wiki, contacts, telephony, sessions, missions, skills, self-mod, channels, MCP) | Clean; mission workers run on POSIX with a real process-group reaper |
diff --git a/jarvis/appshot/service.py b/jarvis/appshot/service.py
index 6200a177ae..7d0cc7846d 100644
--- a/jarvis/appshot/service.py
+++ b/jarvis/appshot/service.py
@@ -178,6 +178,9 @@ async def take_appshot(
trigger,
delivered_to,
)
+ _start_clipboard_copy(
+ shot, trigger, config, selection.action if selection is not None else "done"
+ )
if selection is not None and selection.action != "done":
await _finish_action(selection.action, await finished(shot), bus)
return AppshotResult(
@@ -216,6 +219,10 @@ def _image_size(image: bytes) -> tuple[int, int]:
#: Lossless copies still encoding, by appshot id.
_MASTERS: dict[str, asyncio.Task[Appshot]] = {}
+#: Appshots the user took on purpose; a look the assistant or a spoken
+#: "what do you see?" took never replaces what the user copied.
+_CLIPBOARD_TRIGGERS = frozenset({"hotkey", "button"})
+_COPIES: set[asyncio.Task[None]] = set()
def _start_master(shot: Appshot, markup: Any, config: Any) -> None:
@@ -264,6 +271,36 @@ async def finished(shot: Appshot) -> Appshot:
return held if held is not None else replace(shot, master=None)
+def _start_clipboard_copy(shot: Appshot, trigger: str, config: Any, action: str) -> None:
+ """Put a shortcut or button appshot on the clipboard, ready for Ctrl/Cmd+V.
+
+ Read from ``[appshot].copy_to_clipboard``. The picker's own Copy already
+ copies, so it is not done twice. Runs in the background: the full-quality
+ picture may still be encoding, and the delivery must not wait for it.
+ """
+ if trigger not in _CLIPBOARD_TRIGGERS or action == "copy":
+ return
+ if not bool(getattr(config.appshot, "copy_to_clipboard", True)):
+ return
+ task = asyncio.create_task(_copy_to_clipboard(shot), name="appshot-clipboard")
+ _COPIES.add(task)
+ task.add_done_callback(_COPIES.discard)
+
+
+async def _copy_to_clipboard(shot: Appshot) -> None:
+ try:
+ from jarvis.appshot.card_actions import as_png # noqa: PLC0415
+ from jarvis.platform.clipboard_image import copy_image # noqa: PLC0415
+
+ shot = await finished(shot)
+ png = shot.original_png or await asyncio.to_thread(as_png, shot.image)
+ result = await asyncio.to_thread(copy_image, png)
+ if not result.ok:
+ log.info("appshot: not copied to the clipboard (%s)", result.reason)
+ except Exception: # noqa: BLE001 - the appshot itself is taken and delivered
+ log.warning("appshot: the clipboard copy failed", exc_info=True)
+
+
async def _finish_action(action: str, shot: Appshot, bus: Any | None) -> None:
"""Copy, save or open the appshot, as the picker's toolbar asked."""
try:
diff --git a/jarvis/core/config.py b/jarvis/core/config.py
index 707055c02a..72eb6dfb99 100644
--- a/jarvis/core/config.py
+++ b/jarvis/core/config.py
@@ -2727,6 +2727,11 @@ class AppshotConfig(BaseModel):
#: and ``jarvis.appshot.library``). Off: nothing new is written there.
library: bool = True
+ #: Put every appshot taken by shortcut or button on the system clipboard
+ #: too, so Ctrl/Cmd+V pastes it into any app right away (read by
+ #: ``jarvis.appshot.service``). Looks the assistant takes never copy.
+ copy_to_clipboard: bool = True
+
class JarvisXConfig(BaseModel):
"""Top-level ``[jarvisx]`` config — the built-in screenshot and screen recorder.
diff --git a/jarvis/core/config_writer.py b/jarvis/core/config_writer.py
index 0a94140f13..e60208c6af 100644
--- a/jarvis/core/config_writer.py
+++ b/jarvis/core/config_writer.py
@@ -1000,7 +1000,8 @@ def set_screen_context_settings(
#: Keys ``[appshot]`` accepts — same allowlist reasoning as Screen Context.
#: The master switch is ``[screen_context].enabled``, written by the setter above.
APPSHOT_SETTING_KEYS: frozenset[str] = frozenset(
- {"hotkey", "region_hotkey", "recording_hotkey", "target", "sound", "effect", "card_seconds", "library"}
+ {"hotkey", "region_hotkey", "recording_hotkey", "target", "sound", "effect", "card_seconds", "library",
+ "copy_to_clipboard"}
)
diff --git a/jarvis/jarvisx/clipboard.py b/jarvis/jarvisx/clipboard.py
index 34179573b8..5333930e68 100644
--- a/jarvis/jarvisx/clipboard.py
+++ b/jarvis/jarvisx/clipboard.py
@@ -1,178 +1,29 @@
-"""Put a PNG image on the system clipboard (Windows, macOS, Linux).
+"""Put a Jarvis X screenshot on the system clipboard (Windows, macOS, Linux).
-The app's WebView cannot be trusted with ``navigator.clipboard`` for images,
-so the backend does it natively:
-
-- **Windows** — ``CF_DIB`` (every app pastes it) plus the registered ``PNG``
- format (keeps transparency for apps that prefer it), via ctypes.
-- **macOS** — ``osascript`` with the PNG as ``«class PNGf»``; no extra
- package needed.
-- **Linux** — ``wl-copy`` on Wayland, else ``xclip``; without either the copy
- degrades to a clear message.
-
-Every function returns ``(ok, message)``, never raises, and logs why a copy
-did not happen. Only stdlib at module scope; Pillow loads lazily.
+One native implementation serves the whole app:
+:mod:`jarvis.platform.clipboard_image` offers the picture in every format the
+OS knows (PNG + bitmap on Windows, PNG + TIFF on macOS, ``image/png`` on
+Linux), so Ctrl/Cmd+V pastes it into any app. This module only keeps the
+``(ok, message)`` shape Jarvis X reports in.
"""
from __future__ import annotations
-import ctypes
-import io
import logging
-import os
-import shutil
-import subprocess
-import sys
-import tempfile
-import time
-from pathlib import Path
-
-from jarvis.core.process_utils import NO_WINDOW_CREATIONFLAGS
log = logging.getLogger(__name__)
-_TIMEOUT_S = 5.0
-_RETRIES = 10
-
def copy_png(png: bytes) -> tuple[bool, str]:
- """Replace the clipboard with this PNG image."""
- try:
- from jarvis.platform.probes import display_present # noqa: PLC0415
-
- if not display_present():
- return False, "There is no desktop on this computer, so there is no clipboard."
- except Exception: # noqa: BLE001 - probe missing: try the copy anyway
- log.debug("jarvisx: display probe failed", exc_info=True)
- if sys.platform == "win32":
- return _copy_windows(png)
- if sys.platform == "darwin":
- return _copy_macos(png)
- return _copy_linux(png)
-
-
-def _run(command: list[str], data: bytes | None = None) -> tuple[bool, str]:
- try:
- completed = subprocess.run( # noqa: S603 - fixed OS clipboard command
- command,
- input=data,
- capture_output=True,
- timeout=_TIMEOUT_S,
- check=False,
- close_fds=True,
- creationflags=NO_WINDOW_CREATIONFLAGS,
- )
- except (OSError, subprocess.SubprocessError) as exc:
- log.warning("jarvisx: clipboard command %s failed to run (%s)", command[0], exc)
- return False, "The clipboard tool could not be started."
- if completed.returncode != 0:
- detail = completed.stderr.decode("utf-8", errors="replace").strip()[:300]
- log.warning(
- "jarvisx: clipboard command %s exited %d %s", command[0], completed.returncode, detail
- )
- return False, "The clipboard refused the image."
- return True, "Copied to the clipboard."
-
-
-def _copy_linux(png: bytes) -> tuple[bool, str]:
- if os.environ.get("WAYLAND_DISPLAY") and shutil.which("wl-copy"):
- return _run([str(shutil.which("wl-copy")), "--type", "image/png"], png)
- xclip = shutil.which("xclip")
- if xclip:
- return _run([xclip, "-selection", "clipboard", "-t", "image/png", "-i"], png)
- log.info("jarvisx: no wl-copy or xclip; image copy unavailable")
- return False, "Copying images needs 'xclip' (X11) or 'wl-clipboard' (Wayland) installed."
-
-
-def _copy_macos(png: bytes) -> tuple[bool, str]:
- handle, name = tempfile.mkstemp(prefix="jarvisx-", suffix=".png")
- path = Path(name)
- try:
- with os.fdopen(handle, "wb") as out:
- out.write(png)
- posix = str(path).replace("\\", "\\\\").replace('"', '\\"')
- script = f'set the clipboard to (read (POSIX file "{posix}") as «class PNGf»)'
- return _run(["/usr/bin/osascript", "-e", script])
- finally:
- path.unlink(missing_ok=True)
-
-
-def _dib_bytes(png: bytes) -> bytes:
- """The PNG as a packed DIB (a BMP without its 14-byte file header)."""
- from PIL import Image # noqa: PLC0415
-
- with Image.open(io.BytesIO(png)) as image:
- rgb = image.convert("RGB")
- buffer = io.BytesIO()
- rgb.save(buffer, format="BMP")
- return buffer.getvalue()[14:]
-
-
-def _copy_windows(png: bytes) -> tuple[bool, str]:
- try:
- dib = _dib_bytes(png)
- except Exception as exc: # noqa: BLE001 - a broken image is reported, not raised
- log.warning("jarvisx: image could not be prepared for the clipboard", exc_info=True)
- return False, f"The image could not be read ({exc})."
- try:
- from ctypes import wintypes # noqa: PLC0415
-
- user32 = ctypes.WinDLL("user32", use_last_error=True)
- kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
- user32.OpenClipboard.argtypes = [wintypes.HWND]
- user32.OpenClipboard.restype = wintypes.BOOL
- user32.EmptyClipboard.restype = wintypes.BOOL
- user32.CloseClipboard.restype = wintypes.BOOL
- user32.SetClipboardData.argtypes = [wintypes.UINT, wintypes.HANDLE]
- user32.SetClipboardData.restype = wintypes.HANDLE
- user32.RegisterClipboardFormatW.argtypes = [wintypes.LPCWSTR]
- user32.RegisterClipboardFormatW.restype = wintypes.UINT
- kernel32.GlobalAlloc.argtypes = [wintypes.UINT, ctypes.c_size_t]
- kernel32.GlobalAlloc.restype = wintypes.HGLOBAL
- kernel32.GlobalLock.argtypes = [wintypes.HGLOBAL]
- kernel32.GlobalLock.restype = ctypes.c_void_p
- kernel32.GlobalUnlock.argtypes = [wintypes.HGLOBAL]
- kernel32.GlobalUnlock.restype = wintypes.BOOL
- kernel32.GlobalFree.argtypes = [wintypes.HGLOBAL]
- kernel32.GlobalFree.restype = wintypes.HGLOBAL
- except (AttributeError, OSError) as exc:
- log.warning("jarvisx: Win32 clipboard API unavailable (%s)", exc)
- return False, "The Windows clipboard is not reachable."
-
- def _put(fmt: int, data: bytes) -> bool:
- handle = kernel32.GlobalAlloc(0x0002, len(data)) # GMEM_MOVEABLE
- if not handle:
- return False
- target = kernel32.GlobalLock(handle)
- if not target:
- kernel32.GlobalFree(handle)
- return False
- try:
- ctypes.memmove(target, data, len(data))
- finally:
- kernel32.GlobalUnlock(handle)
- if not user32.SetClipboardData(fmt, handle):
- kernel32.GlobalFree(handle)
- return False
- return True # the clipboard owns the memory now
+ """Replace the clipboard with this PNG image; never raises."""
+ from jarvis.platform.clipboard_image import copy_image # noqa: PLC0415
- for _attempt in range(_RETRIES):
- if user32.OpenClipboard(None):
- break
- time.sleep(0.02)
- else:
- return False, "Another app is holding the clipboard; try again."
try:
- if not user32.EmptyClipboard():
- return False, "The clipboard could not be cleared."
- if not _put(8, dib): # CF_DIB
- return False, "The clipboard refused the image."
- png_format = user32.RegisterClipboardFormatW("PNG")
- if png_format:
- _put(int(png_format), png)
- return True, "Copied to the clipboard."
- finally:
- user32.CloseClipboard()
+ result = copy_image(png)
+ except Exception: # noqa: BLE001 - a failed copy never fails the capture
+ log.warning("jarvisx: clipboard copy failed", exc_info=True)
+ return False, "The clipboard could not be reached."
+ return result.ok, result.message
__all__ = ["copy_png"]
diff --git a/jarvis/platform/clipboard.py b/jarvis/platform/clipboard.py
index 21dbdda15b..7bcb7d4c3b 100644
--- a/jarvis/platform/clipboard.py
+++ b/jarvis/platform/clipboard.py
@@ -17,6 +17,7 @@ import ctypes
import logging
import shutil
import subprocess
+import tempfile
import time
from collections.abc import Sequence
@@ -194,25 +195,30 @@ def _read_windows_native() -> str | None:
def _run_command(command: Sequence[str], text: str) -> bool:
- """Feed clipboard text to a fixed OS command through UTF-8 stdin."""
+ """Feed clipboard text to a fixed OS command through UTF-8 stdin.
+
+ stderr goes to an anonymous file and stdout nowhere, never a pipe:
+ ``xclip``/``xsel``/``wl-copy`` fork a child that keeps serving the
+ clipboard and inherits both, so a pipe would hold ``run`` until timeout.
+ """
try:
- completed = subprocess.run( # noqa: S603 - fixed, non-shell OS command
- list(command),
- input=text,
- capture_output=True,
- text=True,
- encoding="utf-8",
- errors="replace",
- timeout=_COMMAND_TIMEOUT_S,
- check=False,
- close_fds=True,
- creationflags=NO_WINDOW_CREATIONFLAGS,
- )
+ with tempfile.TemporaryFile() as err:
+ completed = subprocess.run( # noqa: S603 - fixed, non-shell OS command
+ list(command),
+ input=text.encode("utf-8"),
+ stdout=subprocess.DEVNULL,
+ stderr=err,
+ timeout=_COMMAND_TIMEOUT_S,
+ check=False,
+ close_fds=True,
+ creationflags=NO_WINDOW_CREATIONFLAGS,
+ )
+ err.seek(0)
+ detail = err.read(4096).decode("utf-8", errors="replace").strip()
except (OSError, subprocess.SubprocessError) as exc:
log.warning("clipboard: native copy command unavailable (%s)", exc)
return False
if completed.returncode != 0:
- detail = (completed.stderr or "").strip()
log.warning(
"clipboard: native copy command failed with exit %d%s",
completed.returncode,
diff --git a/jarvis/platform/clipboard_image.py b/jarvis/platform/clipboard_image.py
index ae4b79c90d..1d194a04af 100644
--- a/jarvis/platform/clipboard_image.py
+++ b/jarvis/platform/clipboard_image.py
@@ -1,18 +1,28 @@
-"""Put a PNG image on the local desktop clipboard (Windows, macOS, Linux).
+"""Put a picture on the local desktop clipboard so Ctrl/Cmd+V pastes it anywhere.
The embedded WebView cannot be trusted with ``navigator.clipboard.write`` for
images: WebView2 may never settle the promise, and WKWebView rejects it once a
-click handler has awaited anything. So the desktop backend copies natively:
+click handler has awaited anything. So the desktop backend copies natively,
+and it puts the SAME picture up in several formats at once, because every app
+asks the clipboard for a different one:
-- **Windows** — ``CF_DIB`` (every app pastes it) plus the registered ``PNG``
- format (keeps transparency for apps that prefer it), through ctypes.
-- **macOS** — ``osascript`` reading the PNG from a temporary file as
- ``«class PNGf»``; no extra package.
-- **Linux** — ``wl-copy`` on Wayland, else ``xclip``; without either the copy
- reports that it cannot happen.
+- **Windows** — the registered ``PNG`` format first (lossless, keeps
+ transparency; browsers, Electron chat apps and Office read it), then
+ ``CF_DIB`` (the classic bitmap every Win32 app pastes; Windows derives
+ ``CF_BITMAP`` and ``CF_DIBV5`` from it). Transparent pixels are laid on
+ white in the bitmap, so they never paste as black.
+- **macOS** — ``public.png`` plus ``public.tiff`` on the general pasteboard,
+ set through the system's JavaScript for Automation bridge (``osascript -l
+ JavaScript``); no extra package. TIFF is the pasteboard's native image type
+ that older Cocoa apps read. Should the bridge fail, AppleScript sets the PNG
+ alone.
+- **Linux** — ``image/png`` through ``wl-copy`` on Wayland, else ``xclip``.
+ Both keep a small process alive that serves the picture until something
+ else is copied; X11/Wayland apps all read ``image/png``. Without either tool
+ the copy reports ``no_tool`` and says which package to install.
-``write_png`` never raises and logs why a copy did not happen. A headless host
-returns ``False`` without touching any OS integration.
+:func:`copy_image` never raises and says why a copy did not happen; a headless
+host returns ``no_display`` without touching any OS integration.
"""
from __future__ import annotations
@@ -25,6 +35,7 @@ import shutil
import subprocess
import tempfile
import time
+from dataclasses import dataclass
from pathlib import Path
from jarvis.core.process_utils import NO_WINDOW_CREATIONFLAGS
@@ -40,104 +51,228 @@ _PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
#: Win32 clipboard format for a device-independent bitmap.
_CF_DIB = 8
_GMEM_MOVEABLE = 0x0002
+#: Pasteboard type -> file suffix for the macOS bridge's staged files.
+_MACOS_TYPES = (("public.png", ".png"), ("public.tiff", ".tiff"))
+
+#: Sets every (type, file) pair given as arguments on the general pasteboard
+#: and prints the types it took. Arguments travel as ``argv``, never spliced
+#: into the script source. The pasteboard is cleared only once some data
+#: loaded, so a failure never leaves it empty. Zero-argument methods are
+#: called by property access (the bridge's idiom); should ``clearContents``
+#: not run, ``setDataForType`` refuses (only the owner may write), nothing is
+#: printed and the AppleScript fallback takes over.
+_MACOS_BRIDGE = """
+function run(argv) {
+ ObjC.import('AppKit');
+ var items = [];
+ for (var i = 0; i + 1 < argv.length; i += 2) {
+ var data = $.NSData.dataWithContentsOfFile(argv[i + 1]);
+ if (!data.isNil()) { items.push([argv[i], data]); }
+ }
+ if (items.length === 0) { return ''; }
+ var board = $.NSPasteboard.generalPasteboard;
+ board.clearContents;
+ var put = [];
+ for (var j = 0; j < items.length; j++) {
+ if (board.setDataForType(items[j][1], items[j][0])) { put.push(items[j][0]); }
+ }
+ return put.join(' ');
+}
+"""
+
+#: User-facing reasons, keyed by :attr:`CopyResult.reason`.
+REASON_MESSAGES = {
+ "": "Copied to the clipboard.",
+ "not_png": "Only PNG pictures can be copied.",
+ "no_display": "There is no desktop on this computer, so there is no clipboard.",
+ "no_tool": "Copying pictures needs 'wl-clipboard' (Wayland) or 'xclip' (X11) installed.",
+ "busy": "Another app is holding the clipboard; try again.",
+ "unreadable": "The picture could not be read.",
+ "refused": "The clipboard refused the picture.",
+ "unavailable": "The clipboard is not reachable.",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class CopyResult:
+ """What a copy did: ``ok``, the formats the OS took, or why it failed."""
+
+ ok: bool
+ #: ``""`` on success, else one key of :data:`REASON_MESSAGES`.
+ reason: str = ""
+ formats: tuple[str, ...] = ()
+
+ @property
+ def message(self) -> str:
+ return REASON_MESSAGES.get(self.reason, REASON_MESSAGES["refused"])
def is_png(data: bytes) -> bool:
return data.startswith(_PNG_SIGNATURE)
-def write_png(png: bytes) -> bool:
- """Replace the clipboard with this PNG. ``True`` only when the OS took it."""
+def copy_image(png: bytes) -> CopyResult:
+ """Replace the clipboard with this PNG, in every format the OS offers."""
if not is_png(png):
log.warning("clipboard-image: refusing a payload that is not a PNG")
- return False
+ return CopyResult(False, "not_png")
if not detect_capabilities().display_present:
log.info("clipboard-image: no display present; native copy is unavailable")
- return False
+ return CopyResult(False, "no_display")
platform = detect_platform()
if platform == "win32":
- return _write_windows(png)
- if platform == "darwin":
- return _write_macos(png)
- return _write_linux(png)
+ result = _write_windows(png)
+ elif platform == "darwin":
+ result = _write_macos(png)
+ else:
+ result = _write_linux(png)
+ if result.ok:
+ log.info("clipboard-image: copied as %s", ", ".join(result.formats))
+ return result
+
+
+def write_png(png: bytes) -> bool:
+ """Replace the clipboard with this PNG. ``True`` only when the OS took it."""
+ return copy_image(png).ok
+
+
+def _has_alpha(image) -> bool: # noqa: ANN001 - a PIL image; Pillow loads lazily
+ return image.mode in ("RGBA", "LA", "PA") or "transparency" in image.info
+
+
+def _flattened(png: bytes): # noqa: ANN202 - a PIL image; Pillow loads lazily
+ """The picture as opaque RGB, transparent parts laid on white."""
+ from PIL import Image # noqa: PLC0415 - Pillow only when an image is copied
+
+ with Image.open(io.BytesIO(png)) as image:
+ if _has_alpha(image):
+ rgba = image.convert("RGBA")
+ backdrop = Image.new("RGB", rgba.size, (255, 255, 255))
+ backdrop.paste(rgba, mask=rgba.getchannel("A"))
+ return backdrop
+ return image.convert("RGB")
def png_to_dib(png: bytes) -> bytes:
"""The PNG as a ``CF_DIB`` payload: a BMP file without its 14-byte header."""
- from PIL import Image # noqa: PLC0415 - Pillow only when an image is copied
+ out = io.BytesIO()
+ _flattened(png).save(out, format="BMP")
+ return out.getvalue()[14:]
+
+
+def png_to_tiff(png: bytes) -> bytes:
+ """The PNG as a TIFF (alpha kept), LZW-compressed where Pillow has libtiff."""
+ from PIL import Image # noqa: PLC0415
with Image.open(io.BytesIO(png)) as image:
- rgb = image.convert("RGB")
+ converted = image.convert("RGBA" if _has_alpha(image) else "RGB")
+ out = io.BytesIO()
+ try:
+ converted.save(out, format="TIFF", compression="tiff_lzw")
+ except (OSError, ValueError):
+ # A Pillow without libtiff writes uncompressed TIFF only.
out = io.BytesIO()
- rgb.save(out, format="BMP")
- return out.getvalue()[14:]
+ converted.save(out, format="TIFF")
+ return out.getvalue()
+
+def _run(command: list[str], data: bytes | None = None) -> tuple[bool, str]:
+ """Run a fixed OS command; ``(ok, stdout)``.
-def _run(command: list[str], data: bytes | None = None) -> bool:
+ stdout and stderr go to an anonymous file, never a pipe: ``xclip`` and
+ ``wl-copy`` fork a child that serves the clipboard and inherits both, so a
+ pipe would stay open until the next copy and ``run`` would wait for it.
+ """
try:
- completed = subprocess.run( # noqa: S603 - fixed, non-shell OS command
- command,
- input=data,
- capture_output=True,
- timeout=_COMMAND_TIMEOUT_S,
- check=False,
- close_fds=True,
- creationflags=NO_WINDOW_CREATIONFLAGS,
- )
+ with tempfile.TemporaryFile() as out, tempfile.TemporaryFile() as err:
+ completed = subprocess.run( # noqa: S603 - fixed, non-shell OS command
+ command,
+ input=data if data is not None else b"",
+ stdout=out,
+ stderr=err,
+ timeout=_COMMAND_TIMEOUT_S,
+ check=False,
+ close_fds=True,
+ creationflags=NO_WINDOW_CREATIONFLAGS,
+ )
+ out.seek(0)
+ err.seek(0)
+ stdout = out.read(4096).decode("utf-8", errors="replace").strip()
+ detail = err.read(4096).decode("utf-8", errors="replace").strip()
except (OSError, subprocess.SubprocessError) as exc:
log.warning("clipboard-image: copy command unavailable (%s)", exc)
- return False
+ return False, ""
if completed.returncode != 0:
- detail = completed.stderr.decode("utf-8", errors="replace").strip()
log.warning(
"clipboard-image: copy command failed with exit %d%s",
completed.returncode,
f" ({detail[:300]})" if detail else "",
)
- return False
- return True
+ return False, ""
+ return True, stdout
-def _write_linux(png: bytes) -> bool:
+def _write_linux(png: bytes) -> CopyResult:
wl_copy = shutil.which("wl-copy")
- if wl_copy and os.environ.get("WAYLAND_DISPLAY"):
- return _run([wl_copy, "--type", "image/png"], png)
xclip = shutil.which("xclip")
- if xclip:
- return _run([xclip, "-selection", "clipboard", "-t", "image/png", "-i"], png)
- if wl_copy:
- return _run([wl_copy, "--type", "image/png"], png)
- log.info("clipboard-image: neither wl-copy nor xclip is installed")
- return False
+ if wl_copy and os.environ.get("WAYLAND_DISPLAY"):
+ command = [wl_copy, "--type", "image/png"]
+ elif xclip:
+ command = [xclip, "-selection", "clipboard", "-t", "image/png", "-i"]
+ elif wl_copy:
+ command = [wl_copy, "--type", "image/png"]
+ else:
+ log.info("clipboard-image: neither wl-copy nor xclip is installed")
+ return CopyResult(False, "no_tool")
+ ok, _stdout = _run(command, png)
+ return CopyResult(True, formats=("image/png",)) if ok else CopyResult(False, "refused")
-def _write_macos(png: bytes) -> bool:
- handle, name = tempfile.mkstemp(prefix="jarvis-appshot-", suffix=".png")
- path = Path(name)
+def _write_macos(png: bytes) -> CopyResult:
+ staged: list[Path] = []
try:
- with os.fdopen(handle, "wb") as file:
- file.write(png)
- # The path travels as an argument to AppleScript's `item 1 of argv`,
- # never spliced into the script source.
+ payloads = {"public.png": png}
+ try:
+ payloads["public.tiff"] = png_to_tiff(png)
+ except Exception: # noqa: BLE001 - the PNG alone still pastes in most apps
+ log.info("clipboard-image: no TIFF rendition; copying the PNG alone", exc_info=True)
+ args: list[str] = []
+ for kind, suffix in _MACOS_TYPES:
+ data = payloads.get(kind)
+ if data is None:
+ continue
+ handle, name = tempfile.mkstemp(prefix="jarvis-clip-", suffix=suffix)
+ path = Path(name)
+ staged.append(path)
+ with os.fdopen(handle, "wb") as file:
+ file.write(data)
+ args += [kind, str(path)]
+ ok, stdout = _run(["/usr/bin/osascript", "-l", "JavaScript", "-e", _MACOS_BRIDGE, *args])
+ formats = tuple(kind for kind in stdout.split() if kind in payloads)
+ if ok and "public.png" in formats:
+ return CopyResult(True, formats=formats)
+ log.info("clipboard-image: pasteboard bridge did not take the PNG; using AppleScript")
script = (
"on run argv\n"
"set the clipboard to (read (POSIX file (item 1 of argv)) as «class PNGf»)\n"
"end run"
)
- return _run(["/usr/bin/osascript", "-e", script, str(path)])
+ ok, _stdout = _run(["/usr/bin/osascript", "-e", script, str(staged[0])])
+ return CopyResult(True, formats=("public.png",)) if ok else CopyResult(False, "refused")
except OSError as exc:
- log.warning("clipboard-image: could not stage the PNG for osascript (%s)", exc)
- return False
+ log.warning("clipboard-image: could not stage the picture for osascript (%s)", exc)
+ return CopyResult(False, "unavailable")
finally:
- path.unlink(missing_ok=True)
+ for path in staged:
+ path.unlink(missing_ok=True)
-def _write_windows(png: bytes) -> bool:
+def _write_windows(png: bytes) -> CopyResult:
try:
dib = png_to_dib(png)
except Exception as exc: # noqa: BLE001 - a picture Pillow cannot read is not copyable
log.warning("clipboard-image: could not convert the PNG to a bitmap (%s)", exc)
- return False
+ return CopyResult(False, "unreadable")
try:
from ctypes import wintypes # noqa: PLC0415
@@ -159,7 +294,7 @@ def _write_windows(png: bytes) -> bool:
kernel32.GlobalFree.argtypes = [wintypes.HGLOBAL]
except (AttributeError, OSError) as exc:
log.warning("clipboard-image: Win32 API unavailable (%s)", exc)
- return False
+ return CopyResult(False, "unavailable")
def put(fmt: int, data: bytes) -> bool:
handle = kernel32.GlobalAlloc(_GMEM_MOVEABLE, len(data))
@@ -185,22 +320,33 @@ def _write_windows(png: bytes) -> bool:
time.sleep(_WINDOWS_CLIPBOARD_RETRY_S)
if not opened:
log.warning("clipboard-image: another application holds the clipboard open")
- return False
+ return CopyResult(False, "busy")
try:
if not user32.EmptyClipboard():
log.warning("clipboard-image: EmptyClipboard failed")
- return False
- if not put(_CF_DIB, dib):
- log.warning("clipboard-image: SetClipboardData(CF_DIB) failed")
- return False
+ return CopyResult(False, "refused")
+ formats: list[str] = []
+ # Format order is the offer order apps see: the lossless PNG first.
png_format = user32.RegisterClipboardFormatW("PNG")
- if png_format and not put(png_format, png):
- # The bitmap is already there and pastes everywhere; the PNG
- # format only adds transparency for apps that read it.
- log.info("clipboard-image: the extra PNG format was not accepted")
- return True
+ if png_format and put(png_format, png):
+ formats.append("PNG")
+ else:
+ log.info("clipboard-image: the PNG format was not accepted")
+ if put(_CF_DIB, dib):
+ formats.append("CF_DIB")
+ else:
+ log.warning("clipboard-image: SetClipboardData(CF_DIB) failed")
+ return CopyResult(True, formats=tuple(formats)) if formats else CopyResult(False, "refused")
finally:
user32.CloseClipboard()
-__all__ = ["is_png", "png_to_dib", "write_png"]
+__all__ = [
+ "REASON_MESSAGES",
+ "CopyResult",
+ "copy_image",
+ "is_png",
+ "png_to_dib",
+ "png_to_tiff",
+ "write_png",
+]
diff --git a/jarvis/ui/web/appshot_routes.py b/jarvis/ui/web/appshot_routes.py
index 52a0ca3f6b..64f186d097 100644
--- a/jarvis/ui/web/appshot_routes.py
+++ b/jarvis/ui/web/appshot_routes.py
@@ -57,6 +57,7 @@ class SettingsPatch(BaseModel):
effect: bool | None = None
card_seconds: int | None = Field(default=None, ge=0, le=600)
library: bool | None = None
+ copy_to_clipboard: bool | None = None
class TakeRequest(BaseModel):
@@ -119,6 +120,7 @@ def _settings_payload() -> dict[str, Any]:
"effect": bool(block.effect),
"card_seconds": int(getattr(block, "card_seconds", 6)),
"library": bool(getattr(block, "library", True)),
+ "copy_to_clipboard": bool(getattr(block, "copy_to_clipboard", True)),
"sound_effects_master": bool(getattr(config.ui, "sound_effects", True)),
"shortcut": _status("window"),
"region_shortcut": _status("region"),
diff --git a/jarvis/ui/web/frontend/src/i18n/locales/appshot_editor/de.json b/jarvis/ui/web/frontend/src/i18n/locales/appshot_editor/de.json
index 6edbb160de..b716f98559 100644
--- a/jarvis/ui/web/frontend/src/i18n/locales/appshot_editor/de.json
+++ b/jarvis/ui/web/frontend/src/i18n/locales/appshot_editor/de.json
@@ -101,6 +101,8 @@
"library_edited_badge": "Bearbeitet",
"library_empty": "Noch keine Appshots. Mach einen mit dem Kürzel, dann erscheint er hier.",
"library_empty_edited": "Noch keine bearbeiteten Appshots. Öffne einen, markiere etwas und speichere.",
+ "clipboard_label": "In die Zwischenablage kopieren",
+ "clipboard_hint": "Jeder Appshot per Tastenkürzel oder Knopf landet auch in der Zwischenablage und lässt sich sofort mit Strg+V einfügen (Cmd+V auf dem Mac).",
"library_label": "Appshot-Verlauf behalten",
"library_hint": "Bewahrt jeden Appshot und jede Bearbeitung auf diesem Computer auf, die neuesten 500. Aus: Neues wird nicht aufbewahrt.",
"library_edit": "Bearbeiten",
diff --git a/jarvis/ui/web/frontend/src/i18n/locales/appshot_editor/en.json b/jarvis/ui/web/frontend/src/i18n/locales/appshot_editor/en.json
index fe18cac10e..c6a6a3e7c6 100644
--- a/jarvis/ui/web/frontend/src/i18n/locales/appshot_editor/en.json
+++ b/jarvis/ui/web/frontend/src/i18n/locales/appshot_editor/en.json
@@ -101,6 +101,8 @@
"library_edited_badge": "Edited",
"library_empty": "No appshots yet. Take one with the shortcut and it shows up here.",
"library_empty_edited": "No edited appshots yet. Open one, mark it up and save.",
+ "clipboard_label": "Copy to clipboard",
+ "clipboard_hint": "Every appshot you take by shortcut or button also goes on the clipboard, ready to paste with Ctrl+V (Cmd+V on a Mac).",
"library_label": "Keep appshot history",
"library_hint": "Keeps every appshot and edit on this computer, the newest 500. Off: nothing new is kept.",
"library_edit": "Edit",
diff --git a/jarvis/ui/web/frontend/src/i18n/locales/appshot_editor/es.json b/jarvis/ui/web/frontend/src/i18n/locales/appshot_editor/es.json
index e1ba150b5f..ac145b1382 100644
--- a/jarvis/ui/web/frontend/src/i18n/locales/appshot_editor/es.json
+++ b/jarvis/ui/web/frontend/src/i18n/locales/appshot_editor/es.json
@@ -101,6 +101,8 @@
"library_edited_badge": "Editado",
"library_empty": "Aún no hay appshots. Haz uno con el atajo y aparecerá aquí.",
"library_empty_edited": "Aún no hay appshots editados. Abre uno, márcalo y guárdalo.",
+ "clipboard_label": "Copiar al portapapeles",
+ "clipboard_hint": "Cada appshot que tomes con un atajo o un botón también va al portapapeles, listo para pegar con Ctrl+V (Cmd+V en un Mac).",
"library_label": "Guardar historial de appshots",
"library_hint": "Guarda cada appshot y cada edición en este equipo, los 500 más recientes. Desactivado: no se guarda nada nuevo.",
"library_edit": "Editar",
diff --git a/jarvis/ui/web/frontend/src/lib/appshotApi.ts b/jarvis/ui/web/frontend/src/lib/appshotApi.ts
index 000aa11099..9219c309ca 100644
--- a/jarvis/ui/web/frontend/src/lib/appshotApi.ts
+++ b/jarvis/ui/web/frontend/src/lib/appshotApi.ts
@@ -30,6 +30,8 @@ export interface AppshotSettings {
card_seconds: number;
/** Keep every appshot and edit in the gallery. Absent on an older backend. */
library?: boolean;
+ /** Copy shortcut and button appshots to the clipboard. Absent on an older backend. */
+ copy_to_clipboard?: boolean;
sound_effects_master: boolean;
shortcut: AppshotShortcutStatus;
region_shortcut: AppshotShortcutStatus;
@@ -58,6 +60,7 @@ export type AppshotSettingsPatch = Partial<
Pick<
AppshotSettings,
"enabled" | "hotkey" | "region_hotkey" | "recording_hotkey" | "target" | "sound" | "effect" | "card_seconds" | "library"
+ | "copy_to_clipboard"
>
>;
diff --git a/jarvis/ui/web/frontend/src/views/AppshotsView.test.tsx b/jarvis/ui/web/frontend/src/views/AppshotsView.test.tsx
index 5fffbe0f33..208caff1d0 100644
--- a/jarvis/ui/web/frontend/src/views/AppshotsView.test.tsx
+++ b/jarvis/ui/web/frontend/src/views/AppshotsView.test.tsx
@@ -77,6 +77,40 @@ describe("AppshotsView", () => {
expect(Object.keys(JSON.parse(String(put[1].body)))).toEqual(["sound"]);
});
+ it("saves the clipboard switch on its own", async () => {
+ const withClipboard = { ...SETTINGS, copy_to_clipboard: true };
+ fetchMock.mockImplementation(async (url: string, init?: RequestInit) => {
+ if (url === "/api/appshot/settings" && init?.method === "PUT") {
+ return json({ ...withClipboard, ...JSON.parse(String(init.body)) });
+ }
+ if (url === "/api/appshot/settings") return json(withClipboard);
+ if (url === "/api/appshot/latest") return json({ appshot: null });
+ return json({}, 404);
+ });
+ render(<AppshotsView />);
+ const toggle = await screen.findByTestId("appshots-clipboard");
+ expect(toggle.getAttribute("data-state")).toBe("checked");
+ fireEvent.click(toggle);
+ await waitFor(() =>
+ expect(
+ fetchMock.mock.calls.some(
+ ([url, init]) =>
+ url === "/api/appshot/settings" &&
+ init?.method === "PUT" &&
+ JSON.parse(String(init.body)).copy_to_clipboard === false,
+ ),
+ ).toBe(true),
+ );
+ const put = fetchMock.mock.calls.find(([, init]) => init?.method === "PUT")!;
+ expect(Object.keys(JSON.parse(String(put[1].body)))).toEqual(["copy_to_clipboard"]);
+ });
+
+ it("hides the clipboard switch while an older backend is still running", async () => {
+ render(<AppshotsView />);
+ await screen.findByTestId("appshots-sound");
+ expect(screen.queryByTestId("appshots-clipboard")).toBeNull();
+ });
+
it("disables every other control while appshots are switched off", async () => {
fetchMock.mockImplementation(async (url: string) =>
url === "/api/appshot/settings"
diff --git a/jarvis/ui/web/frontend/src/views/AppshotsView.tsx b/jarvis/ui/web/frontend/src/views/AppshotsView.tsx
index 2e58e92470..556fdaa580 100644
--- a/jarvis/ui/web/frontend/src/views/AppshotsView.tsx
+++ b/jarvis/ui/web/frontend/src/views/AppshotsView.tsx
@@ -563,6 +563,21 @@ export function AppshotsView() {
}
/>
)}
+ {typeof settings.copy_to_clipboard === "boolean" && (
+ <Row
+ label={editorReady ? t("appshot_editor.clipboard_label") : ""}
+ hint={editorReady ? t("appshot_editor.clipboard_hint") : ""}
+ control={
+ <Switch
+ checked={settings.copy_to_clipboard}
+ disabled={saving}
+ aria-label={editorReady ? t("appshot_editor.clipboard_label") : ""}
+ data-testid="appshots-clipboard"
+ onCheckedChange={(copy_to_clipboard) => void save({ copy_to_clipboard })}
+ />
+ }
+ />
+ )}
<Row
label={t("appshots.try_label")}
hint={
diff --git a/tests/unit/appshot/test_appshot_clipboard.py b/tests/unit/appshot/test_appshot_clipboard.py
new file mode 100644
index 0000000000..e9be37f9b8
--- /dev/null
+++ b/tests/unit/appshot/test_appshot_clipboard.py
@@ -0,0 +1,139 @@
+"""An appshot the user takes lands on the clipboard, ready for Ctrl/Cmd+V."""
+
+from __future__ import annotations
+
+import asyncio
+import io
+from dataclasses import replace
+from types import SimpleNamespace
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+from PIL import Image
+
+from jarvis.appshot import service
+from jarvis.appshot.store import Appshot
+from jarvis.platform import clipboard_image
+
+
+def _png() -> bytes:
+ buffer = io.BytesIO()
+ Image.new("RGB", (40, 30), (20, 120, 220)).save(buffer, "PNG")
+ return buffer.getvalue()
+
+
+def _shot(trigger: str = "hotkey") -> Appshot:
+ return Appshot(
+ id="c0ffee00",
+ image=_png(),
+ mime="image/png",
+ width=40,
+ height=30,
+ label="selected area",
+ app_name="Editor",
+ note="APPSHOT: evidence",
+ ui_text="",
+ trigger=trigger,
+ taken_at=1.0,
+ )
+
+
+def _config(copy: bool = True) -> SimpleNamespace:
+ return SimpleNamespace(appshot=SimpleNamespace(copy_to_clipboard=copy))
+
+
+def copied(monkeypatch: pytest.MonkeyPatch) -> list[bytes]:
+ pasted: list[bytes] = []
+
+ def fake_copy(png: bytes) -> clipboard_image.CopyResult:
+ pasted.append(png)
+ return clipboard_image.CopyResult(True, formats=("PNG",))
+
+ async def no_master(shot: Appshot) -> Appshot:
+ return shot
+
+ monkeypatch.setattr(clipboard_image, "copy_image", fake_copy)
+ monkeypatch.setattr(service, "finished", no_master)
+ return pasted
+
+
+async def _settle() -> None:
+ while service._COPIES: # noqa: SLF001
+ await asyncio.gather(*service._COPIES) # noqa: SLF001
+
+
[email protected]("trigger", ["hotkey", "button"])
+async def test_a_shortcut_or_button_appshot_is_copied(copied: list[bytes], trigger: str) -> None:
+ service._start_clipboard_copy(_shot(trigger), trigger, _config(), "done") # noqa: SLF001
+ await _settle()
+
+ assert copied == [_png()]
+
+
[email protected]("trigger", ["voice", "tool"])
+async def test_a_look_the_assistant_took_never_replaces_the_clipboard(
+ copied: list[bytes], trigger: str
+) -> None:
+ service._start_clipboard_copy(_shot(trigger), trigger, _config(), "done") # noqa: SLF001
+ await _settle()
+
+ assert copied == []
+
+
+async def test_the_setting_switches_it_off(copied: list[bytes]) -> None:
+ service._start_clipboard_copy(_shot(), "hotkey", _config(copy=False), "done") # noqa: SLF001
+ await _settle()
+
+ assert copied == []
+
+
+async def test_the_pickers_own_copy_is_not_done_twice(copied: list[bytes]) -> None:
+ service._start_clipboard_copy(_shot(), "hotkey", _config(), "copy") # noqa: SLF001
+ await _settle()
+
+ assert copied == []
+
+
+async def test_the_lossless_picture_is_what_gets_copied(
+ monkeypatch: pytest.MonkeyPatch, copied: list[bytes]
+) -> None:
+ master = _png() + b"lossless"
+
+ async def finished(shot: Appshot) -> Appshot:
+ return replace(shot, original_png=master)
+
+ monkeypatch.setattr(service, "finished", finished)
+ service._start_clipboard_copy(_shot(), "hotkey", _config(), "done") # noqa: SLF001
+ await _settle()
+
+ assert copied == [master]
+
+
+def test_copy_to_clipboard_defaults_on_and_is_a_settings_key() -> None:
+ from jarvis.core.config import AppshotConfig
+ from jarvis.core.config_writer import APPSHOT_SETTING_KEYS
+
+ assert AppshotConfig().copy_to_clipboard is True
+ assert "copy_to_clipboard" in APPSHOT_SETTING_KEYS
+
+
+def test_the_settings_route_reads_and_writes_the_switch(
+ monkeypatch: pytest.MonkeyPatch, tmp_path
+) -> None:
+ from jarvis.core import config_writer
+ from jarvis.ui.web import appshot_routes
+
+ written: list[dict] = []
+ monkeypatch.setattr(
+ config_writer, "set_appshot_settings", lambda values, **_kw: written.append(values)
+ )
+ monkeypatch.setattr(appshot_routes, "_settings_payload", lambda: {"copy_to_clipboard": False})
+ app = FastAPI()
+ app.include_router(appshot_routes.router)
+
+ response = TestClient(app).put("/api/appshot/settings", json={"copy_to_clipboard": False})
+
+ assert response.status_code == 200, response.text
+ assert written == [{"copy_to_clipboard": False}]
diff --git a/tests/unit/appshot/test_appshot_editor.py b/tests/unit/appshot/test_appshot_editor.py
index d464f463aa..0b5d45d251 100644
--- a/tests/unit/appshot/test_appshot_editor.py
+++ b/tests/unit/appshot/test_appshot_editor.py
@@ -238,10 +238,10 @@ def test_clipboard_image_picks_the_linux_tool(
clipboard_image.shutil, "which", lambda name: f"/usr/bin/{name}" if name in tools else None
)
monkeypatch.setattr(
- clipboard_image, "_run", lambda command, data=None: ran.append(command) or True
+ clipboard_image, "_run", lambda command, data=None: (ran.append(command) or True, "")
)
- ok = clipboard_image._write_linux(_png()) # noqa: SLF001
+ ok = clipboard_image._write_linux(_png()).ok # noqa: SLF001
assert ok is (expected is not None)
assert [command[0] for command in ran] == ([f"/usr/bin/{expected}"] if expected else [])
diff --git a/tests/unit/platform/test_clipboard.py b/tests/unit/platform/test_clipboard.py
index 948a4d262e..7dcd07c29a 100644
--- a/tests/unit/platform/test_clipboard.py
+++ b/tests/unit/platform/test_clipboard.py
@@ -99,7 +99,9 @@ def test_command_writer_passes_text_only_through_stdin(
assert clipboard._run_command(["pbcopy"], clipboard_text) is True
assert captured["command"] == ["pbcopy"]
- assert captured["input"] == clipboard_text
+ assert captured["input"] == clipboard_text.encode("utf-8")
+ # A forked clipboard owner must not hold a pipe open (xclip, wl-copy).
+ assert captured["stdout"] is subprocess.DEVNULL
assert clipboard_text not in captured["command"]
diff --git a/tests/unit/platform/test_clipboard_image.py b/tests/unit/platform/test_clipboard_image.py
new file mode 100644
index 0000000000..56b73e8e02
--- /dev/null
+++ b/tests/unit/platform/test_clipboard_image.py
@@ -0,0 +1,207 @@
+"""The picture clipboard: one image, every format the OS knows, on every OS."""
+
+from __future__ import annotations
+
+import io
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+from PIL import Image
+
+from jarvis.platform import clipboard_image
+
+
+def _png(width: int = 8, height: int = 6, *, alpha: bool = False) -> bytes:
+ if alpha:
+ image = Image.new("RGBA", (width, height), (0, 0, 0, 0))
+ image.putpixel((0, 0), (200, 10, 10, 255))
+ else:
+ image = Image.new("RGB", (width, height), (20, 120, 220))
+ buffer = io.BytesIO()
+ image.save(buffer, "PNG")
+ return buffer.getvalue()
+
+
+def desktop(monkeypatch: pytest.MonkeyPatch):
+ def use(platform: str) -> None:
+ monkeypatch.setattr(
+ clipboard_image, "detect_capabilities", lambda: SimpleNamespace(display_present=True)
+ )
+ monkeypatch.setattr(clipboard_image, "detect_platform", lambda: platform)
+
+ return use
+
+
+def test_a_payload_that_is_not_a_png_is_refused() -> None:
+ result = clipboard_image.copy_image(b"GIF89a")
+
+ assert result == clipboard_image.CopyResult(False, "not_png")
+ assert result.message == "Only PNG pictures can be copied."
+
+
+def test_a_headless_host_never_touches_the_os(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(
+ clipboard_image, "detect_capabilities", lambda: SimpleNamespace(display_present=False)
+ )
+
+ def unexpected(_png: bytes) -> clipboard_image.CopyResult:
+ raise AssertionError("no OS integration on a headless host")
+
+ for name in ("_write_windows", "_write_macos", "_write_linux"):
+ monkeypatch.setattr(clipboard_image, name, unexpected)
+
+ assert clipboard_image.copy_image(_png()).reason == "no_display"
+ assert clipboard_image.write_png(_png()) is False
+
+
+def test_transparent_pixels_become_white_in_the_bitmap() -> None:
+ dib = clipboard_image.png_to_dib(_png(alpha=True))
+ # Re-wrap the packed DIB as a BMP file to read it back.
+ header = b"BM" + (14 + len(dib)).to_bytes(4, "little") + b"\0\0\0\0"
+ header += (14 + int.from_bytes(dib[0:4], "little")).to_bytes(4, "little")
+ with Image.open(io.BytesIO(header + dib)) as bitmap:
+ rgb = bitmap.convert("RGB")
+ assert rgb.getpixel((0, 0)) == (200, 10, 10)
+ assert rgb.getpixel((5, 4)) == (255, 255, 255)
+
+
+def test_the_tiff_rendition_keeps_transparency() -> None:
+ tiff = clipboard_image.png_to_tiff(_png(alpha=True))
+
+ with Image.open(io.BytesIO(tiff)) as image:
+ assert image.format == "TIFF"
+ assert image.mode == "RGBA"
+ assert image.getpixel((5, 4))[3] == 0
+
+
+def test_a_palette_picture_keeps_its_transparency_in_the_tiff() -> None:
+ palette = Image.new("RGBA", (4, 4), (0, 0, 0, 0)).convert("P")
+ buffer = io.BytesIO()
+ palette.save(buffer, "PNG", transparency=0)
+
+ with Image.open(io.BytesIO(clipboard_image.png_to_tiff(buffer.getvalue()))) as image:
+ assert image.mode == "RGBA"
+
+
+def test_the_macos_bridge_is_valid_javascript(tmp_path: Path) -> None:
+ node = shutil.which("node")
+ if node is None:
+ pytest.skip("node is not installed")
+ script = tmp_path / "bridge.js"
+ script.write_text(clipboard_image._MACOS_BRIDGE, encoding="utf-8") # noqa: SLF001
+
+ assert subprocess.run([node, "--check", str(script)], check=False).returncode == 0
+
+
+def test_macos_sets_png_and_tiff_on_the_pasteboard(
+ monkeypatch: pytest.MonkeyPatch, desktop
+) -> None:
+ desktop("darwin")
+ calls: list[list[str]] = []
+ staged: dict[str, bytes] = {}
+
+ def fake_run(command: list[str], data: bytes | None = None) -> tuple[bool, str]:
+ calls.append(command)
+ pairs = command[5:]
+ for kind, path in zip(pairs[0::2], pairs[1::2], strict=True):
+ staged[kind] = Path(path).read_bytes()
+ return True, "public.png public.tiff"
+
+ monkeypatch.setattr(clipboard_image, "_run", fake_run)
+ png = _png()
+
+ result = clipboard_image.copy_image(png)
+
+ assert result.ok and result.formats == ("public.png", "public.tiff")
+ assert len(calls) == 1
+ assert calls[0][:5] == [
+ "/usr/bin/osascript", "-l", "JavaScript", "-e", clipboard_image._MACOS_BRIDGE # noqa: SLF001
+ ]
+ assert staged["public.png"] == png
+ assert staged["public.tiff"].startswith((b"II*\0", b"MM\0*"))
+ # The staged files are gone once the pasteboard holds the data.
+ assert not any(Path(path).exists() for path in calls[0][6::2])
+
+
+def test_macos_falls_back_to_applescript_when_the_bridge_fails(
+ monkeypatch: pytest.MonkeyPatch, desktop
+) -> None:
+ desktop("darwin")
+ calls: list[list[str]] = []
+
+ def fake_run(command: list[str], data: bytes | None = None) -> tuple[bool, str]:
+ calls.append(command)
+ return (False, "") if "JavaScript" in command else (True, "")
+
+ monkeypatch.setattr(clipboard_image, "_run", fake_run)
+
+ result = clipboard_image.copy_image(_png())
+
+ assert result.ok and result.formats == ("public.png",)
+ assert len(calls) == 2
+ assert "«class PNGf»" in calls[1][2]
+ assert calls[1][3].endswith(".png")
+
+
+def test_linux_without_a_clipboard_tool_says_what_to_install(
+ monkeypatch: pytest.MonkeyPatch, desktop
+) -> None:
+ desktop("linux")
+ monkeypatch.setattr(clipboard_image.shutil, "which", lambda _name: None)
+
+ result = clipboard_image.copy_image(_png())
+
+ assert result.reason == "no_tool"
+ assert "xclip" in result.message and "wl-clipboard" in result.message
+
+
+def test_linux_hands_the_png_to_xclip_on_x11(monkeypatch: pytest.MonkeyPatch, desktop) -> None:
+ desktop("linux")
+ monkeypatch.delenv("WAYLAND_DISPLAY", raising=False)
+ monkeypatch.setattr(clipboard_image.shutil, "which", lambda name: f"/usr/bin/{name}")
+ fed: list[tuple[list[str], bytes | None]] = []
+ def fake_run(command: list[str], data: bytes | None = None) -> tuple[bool, str]:
+ fed.append((command, data))
+ return True, ""
+
+ monkeypatch.setattr(clipboard_image, "_run", fake_run)
+ png = _png()
+
+ result = clipboard_image.copy_image(png)
+
+ assert result.ok and result.formats == ("image/png",)
+ assert fed == [(["/usr/bin/xclip", "-selection", "clipboard", "-t", "image/png", "-i"], png)]
+
+
+def test_the_runner_does_not_wait_for_a_forked_clipboard_owner() -> None:
+ """xclip and wl-copy leave a child serving the clipboard; it holds stdout."""
+ child = "import time; time.sleep(4)"
+ parent = (
+ "import subprocess, sys; "
+ f"subprocess.Popen([sys.executable, '-c', {child!r}]); "
+ "print('served')"
+ )
+ started = time.monotonic()
+
+ ok, stdout = clipboard_image._run([sys.executable, "-c", parent], b"") # noqa: SLF001
+
+ assert ok is True
+ assert stdout == "served"
+ assert time.monotonic() - started < 3.0
+
+
+def test_a_failing_command_reports_false() -> None:
+ ok, _stdout = clipboard_image._run( # noqa: SLF001
+ [sys.executable, "-c", "import sys; sys.stderr.write('no display'); sys.exit(1)"]
+ )
+ assert ok is False
+
+
+def test_a_missing_command_reports_false() -> None:
+ assert clipboard_image._run(["jarvis-no-such-clipboard-tool"]) == (False, "") # noqa: SLF001