dsh-screenshoot

DSH-плагин для снимков экрана и окон. Кроссплатформенный: Windows, macOS, Linux (X11).

Главное отличие от обычного «скриншота экрана»: окно снимается по своим пикселям, поэтому
снимок получается, даже если окно за другим окном, свёрнуто в фоне или не в фокусе. Кино на
переднем плане и приложение агента за ним — не помеха.

Инструменты

Область обрезается по границам виртуального рабочего стола: если она выходит за экран,
снимок делается по пересечению и в подписи появляется clamped, а если пересечения нет —
возвращается понятная ошибка со размерами рабочего стола.

У всех трёх снимков есть delayMs — подождать перед съёмкой (до 30 с). Полезно, когда открывается
меню, проигрывается анимация или окно ещё не перерисовалось.

Все снимки сохраняются в PNG, путь возвращается в результате — его можно открыть
инструментом read_image, чтобы посмотреть на картинку.

Кусок окна

Окно можно снять не целиком, а вырезать прямоугольник относительно его верхнего левого угла:

screen_capture_window { pid: 11184, crop: { x: 40, y: 60, width: 420, height: 240 } }
→ window 420×240 … · crop 420×240 at 40,60

Координаты считаются от угла окна (верхняя левая точка содержимого), а не от экрана.
Если прямоугольник выходит за пределы снимка, возвращается ошибка с размерами картинки —
молча обрезать по краю не будем.

Кроп работает на всех платформах: снимок делается платформенным способом, затем PNG
обрезается встроенным декодером (src/png.js), без ImageMagick и без внешних зависимостей.

Снимки в чате

Как в Browser: после снимка в строке инструмента появляется миниатюра. Хост поднимает
локальный сервер кадров на 127.0.0.1:49231, инструмент возвращает маркер [shot:],
а клиент рисует по нему ``. В памяти держатся последние 24 кадра, файлы остаются на диске.

Клик по миниатюре открывает PNG в новой вкладке.

Как это работает по платформам

Windows — PowerShell + Win32:

• EnumWindows + DwmGetWindowAttribute — список окон и точные границы;
• PrintWindow(PW_RENDERFULLCONTENT) — отрисовка окна в bitmap, не копирование экрана;
  именно поэтому снимается и перекрытое окно;
• Graphics.CopyFromScreen — монитор и область;
• per-monitor DPI awareness — координаты и размеры в физических пикселях (важно на 200 %).
• Заголовки окон передаются в base64, а stdout принудительно UTF-8 — иначе кириллица ломается.

macOS — screencapture + JavaScript for Automation:

• NSScreen — мониторы;
• CGWindowListCopyWindowInfo — окна и их границы;
• screencapture -l — окно, даже перекрытое; -R — область; -D — монитор.

Нужно разрешение Screen Recording (Системные настройки → Конфиденциальность). Без него
macOS отдаст только обои.

Linux (X11) — xrandr, wmctrl, ImageMagick import:

• xrandr --query — мониторы;
• wmctrl -lGpx — окна, pid и геометрия;
• import -window — окно из его собственного буфера; -window root -crop — область.

На Wayland X11-инструменты не видят окна: плагин честно скажет, чего не хватает, вместо
чёрного снимка. Для Wayland нужен portal/grim-подход.

Установка

npx --yes github:machine202502/dsh-screenshoot

или вручную: добавить в ~/.dsh/profiles/desktop/package.json

{
"dependencies": { "dsh-screenshoot": "github:machine202502/dsh-screenshoot" },
"dsh": { "profile": { "bundles": ["…", "dsh-screenshoot"] } }
}

и перезапустить DSH. Плагин не тянет npm-зависимостей — только системные средства платформы.

Примеры

screen_monitors
→ 0* 3200x2000 at 0,0

screen_windows { title: "Brave" }
→ 132518  pid 9800  3200x1904 at 0,0  machine202502/dsh-browser – Brave

screen_capture_window { title: "Brave" }
→ путь к PNG 3200x1904 (окно было за DSH)

screen_capture_region { x: 100, y: 100, width: 800, height: 500 }
screen_capture_monitor { monitor: 0 }

Требования

Проверка

node tests/probe.mjs   # бэкенд платформы напрямую
node tests/smoke.mjs   # инструменты через index.js