@yfwu2020/dsh-selection-explain 0.11.1 → 0.13.0

package/lib/host/shot.js

@@ -0,0 +1,968 @@
+import { spawn, execFile } from 'node:child_process';
+import { readFile, mkdir, rm, stat, chmod, readdir } from 'node:fs/promises';
+import { tmpdir, platform } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { sendJson, readBody } from './http.js';
+/** 截图二进制（系统自带）。 */
+const CAPTURE = '/usr/sbin/screencapture';
+/** 交互式框选 + 整窗截图的总超时：用户可能慢慢框，给足 90 秒。 */
+const SELECT_TIMEOUT_MS = 90_000;
+/**
+ * 让"等待外部事件"的定时器不参与事件循环存活判定。
+ * 宿主进程退出/更新时，这类等待（长轮询、外部命令超时）没有继续存在的意义，
+ * 但一个普通的 setTimeout 会把进程钉住，直到它自己到期。
+ */
+function unrefTimer(timer) {
+    ;
+    timer?.unref?.();
+}
+/** 窗口列表探针（随包编译，见 native/window-list.c）。 */
+export function resolveWindowProbe() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // lib/host/shot.js → lib/native/window-list
+    return join(here, '..', 'native', 'window-list');
+}
+const SHOT_SCOPES = ['screen', 'window', 'margin', 'selection'];
+/** 超出这个尺寸的选区留白没有意义，且会把截图撑得很大。 */
+const MAX_MARGIN_PT = 400;
+/** 只保留最近几张临时图：客户端取图后就不需要旧文件了，但留几张给重试 / 诊断。 */
+const KEEP_SHOTS = 3;
+const state = {
+    available: false,
+    reason: 'idle',
+    capturing: false,
+    pending: null,
+    pendingError: null,
+    lastShot: null,
+    lastError: '',
+    total: 0,
+};
+/** 长轮询的等待者（成功或失败都会叫醒）。 */
+const waiters = [];
+/** 每次截图递增；临时文件名与事件 id 都用它，避免第二张图覆盖第一张。 */
+let seq = 0;
+/** 窗口列表探针是否可用（懒探测一次）。截图范围不依赖它时不会被它拦住。 */
+let probeChecked = false;
+let probeReady = false;
+/** 框选期间预热的窗口列表 / 显示器列表：松手时就不用再等这几十毫秒。 */
+let prefetchedWindows = null;
+let prefetchedDisplays = null;
+function tmpDir() {
+    return join(tmpdir(), 'dsh-selection-explain');
+}
+/** 临时目录只给当前用户读写：截图里可能有敏感内容。 */
+async function ensureTmpDir() {
+    const dir = tmpDir();
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await chmod(dir, 0o700).catch(() => { });
+    return dir;
+}
+function run(cmd, args, timeout = 10_000) {
+    return new Promise((resolve) => {
+        execFile(cmd, args, { timeout, maxBuffer: 8 * 1024 * 1024 }, (error, stdout) => {
+            resolve(error ? '' : String(stdout || ''));
+        });
+    });
+}
+/** 平台是否受支持（目前只做 macOS：整窗截图与矩形都依赖它）。 */
+export function shotSupported() {
+    return platform() === 'darwin';
+}
+/** 平台可用性（不影响窗口探针的结论）。 */
+function ensureCaptureAvailable() {
+    const ok = shotSupported();
+    state.available = ok;
+    state.reason = ok ? 'ok' : 'not-macos';
+    return ok;
+}
+/** 探针在不在（编不出来就只在「整窗」这一档降级，不影响选区/留白/全屏）。 */
+async function probeAvailable() {
+    if (probeChecked)
+        return probeReady;
+    probeChecked = true;
+    if (!shotSupported()) {
+        probeReady = false;
+        return false;
+    }
+    const probe = resolveWindowProbe();
+    probeReady = await stat(probe).then((s) => s.size > 0).catch(() => false);
+    return probeReady;
+}
+async function listWindows() {
+    const raw = await run(resolveWindowProbe(), []);
+    if (!raw.trim())
+        return [];
+    try {
+        const arr = JSON.parse(raw);
+        return Array.isArray(arr) ? arr : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** 活跃显示器的全局矩形（点）与像素尺寸。 */
+async function listDisplays() {
+    const raw = await run(resolveWindowProbe(), ['--displays']);
+    if (!raw.trim())
+        return [];
+    try {
+        const arr = JSON.parse(raw);
+        return Array.isArray(arr)
+            ? arr
+                .filter((item) => Number.isFinite(item?.x) && Number.isFinite(item?.y) && Number.isFinite(item?.w) && Number.isFinite(item?.h))
+                .map((item) => ({
+                id: Number(item.id) || 0,
+                x: Number(item.x),
+                y: Number(item.y),
+                w: Number(item.w),
+                h: Number(item.h),
+                index: Number(item.index) || 0,
+                main: item.main === true || Number(item.main) === 1,
+            }))
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+function intersectArea(a, b) {
+    const left = Math.max(a.x, b.x);
+    const top = Math.max(a.y, b.y);
+    const right = Math.min(a.x + a.width, b.x + b.w);
+    const bottom = Math.min(a.y + a.height, b.y + b.h);
+    return Math.max(0, right - left) * Math.max(0, bottom - top);
+}
+/**
+ * 选区中心落在哪块屏。
+ *
+ * 用中心而不是"交集最大"：选区跨屏时，按中心裁到一块屏才能保证**统一缩放**
+ * （混合 DPI 下 `screencapture -R` 跨屏的像素比例不是线性的）。
+ */
+function pickDisplay(displays, rect) {
+    if (displays.length === 0)
+        return null;
+    const cx = rect.x + rect.width / 2;
+    const cy = rect.y + rect.height / 2;
+    const hits = displays.filter((d) => cx >= d.x && cx <= d.x + d.w && cy >= d.y && cy <= d.y + d.h);
+    if (hits.length > 0)
+        return hits[0];
+    const sorted = displays.slice().sort((a, b) => intersectArea(rect, b) - intersectArea(rect, a));
+    return sorted[0] || displays.find((d) => d.main) || null;
+}
+function clampRect(rect, box) {
+    const left = Math.max(rect.x, box.x);
+    const top = Math.max(rect.y, box.y);
+    const right = Math.min(rect.x + rect.width, box.x + box.w);
+    const bottom = Math.min(rect.y + rect.height, box.y + box.h);
+    return { x: left, y: top, width: Math.max(0, right - left), height: Math.max(0, bottom - top) };
+}
+/**
+ * 读截图文件自带的矩形（全局点），`kMDItemScreenCaptureGlobalRect`。
+ *
+ * ⚠️ 这是 **binary plist**，不能"按顺序读 4 个 double"：
+ * plist 会**去重相同的值** —— 比如一次 300×200 的框选，x=300、w=300、y=200、h=200，
+ * 库里只存两个 double，数组的四个引用指向它们；按顺序读就会读到 [300,200] 然后跑偏。
+ * （实测：正因为这个，有些框准、有些框飘，取决于四个数有没有重复。）
+ *
+ * 所以这里按 plist 结构解：trailer → 偏移表 → 对象表 → 数组引用 → 每个值。
+ */
+function parseRectPlist(buf) {
+    if (buf.length < 40 || buf.toString('latin1', 0, 6) !== 'bplist')
+        return null;
+    const trailer = buf.subarray(buf.length - 32);
+    const offsetSize = trailer[6];
+    const refSize = trailer[7];
+    const numObjects = Number(trailer.readBigUInt64BE(8));
+    const topObject = Number(trailer.readBigUInt64BE(16));
+    const tableOffset = Number(trailer.readBigUInt64BE(24));
+    if (!numObjects || offsetSize < 1 || offsetSize > 8 || refSize < 1 || refSize > 8)
+        return null;
+    if (tableOffset + numObjects * offsetSize > buf.length)
+        return null;
+    const readSized = (at, size) => {
+        let value = 0;
+        for (let i = 0; i < size; i += 1)
+            value = value * 256 + buf[at + i];
+        return value;
+    };
+    const objectAt = (index) => {
+        if (index >= numObjects)
+            return -1;
+        return readSized(tableOffset + index * offsetSize, offsetSize);
+    };
+    /** 把某个对象解成一个数字（int / real / double）。 */
+    const readNumber = (at) => {
+        if (at < 0 || at >= buf.length)
+            return null;
+        const marker = buf[at];
+        const kind = marker >> 4;
+        const sizeBits = marker & 0x0f;
+        if (kind === 0x1) {
+            // int
+            const size = 1 << sizeBits;
+            if (size > 8)
+                return null;
+            let value = 0;
+            for (let i = 0; i < size; i += 1)
+                value = value * 256 + buf[at + 1 + i];
+            return value;
+        }
+        if (kind === 0x2) {
+            // real（0x22 float32 / 0x23 float64）
+            if (sizeBits === 2)
+                return buf.readFloatBE(at + 1);
+            if (sizeBits === 3)
+                return buf.readDoubleBE(at + 1);
+        }
+        return null;
+    };
+    const arrayAt = objectAt(topObject);
+    if (arrayAt < 0)
+        return null;
+    const marker = buf[arrayAt];
+    if (marker >> 4 !== 0xa)
+        return null;
+    let count = marker & 0x0f;
+    let refsAt = arrayAt + 1;
+    if (count === 0x0f) {
+        // 长数组：后面跟一个 int 表示数量
+        const intMarker = buf[refsAt];
+        const size = 1 << (intMarker & 0x0f);
+        let value = 0;
+        for (let i = 0; i < size; i += 1)
+            value = value * 256 + buf[refsAt + 1 + i];
+        count = value;
+        refsAt += 1 + size;
+    }
+    const out = [];
+    for (let i = 0; i < count; i += 1) {
+        const ref = readSized(refsAt + i * refSize, refSize);
+        const value = readNumber(objectAt(ref));
+        if (value === null)
+            return null;
+        out.push(value);
+    }
+    return out;
+}
+/** 从截图文件的扩展属性里读矩形（点）。 */
+async function rectFromXattr(file) {
+    const hex = (await run('/usr/bin/xattr', ['-px', 'com.apple.metadata:kMDItemScreenCaptureGlobalRect', file])).replace(/\s+/g, '');
+    if (!hex || hex.length % 2 !== 0)
+        return null;
+    let buf;
+    try {
+        buf = Buffer.from(hex, 'hex');
+    }
+    catch {
+        return null;
+    }
+    const nums = parseRectPlist(buf);
+    if (!nums || nums.length < 4)
+        return null;
+    const [x, y, w, h] = nums;
+    if (![x, y, w, h].every(Number.isFinite) || w <= 0 || h <= 0)
+        return null;
+    return { x, y, width: w, height: h };
+}
+/** 一张图的像素尺寸（不引图像库：读 PNG 的 IHDR 就够）。 */
+async function pngSize(file) {
+    try {
+        const buf = await readFile(file);
+        if (buf.length < 24)
+            return null;
+        const isPng = buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47;
+        if (!isPng)
+            return null;
+        return { w: buf.readUInt32BE(16), h: buf.readUInt32BE(20) };
+    }
+    catch {
+        return null;
+    }
+}
+function contains(win, rect) {
+    const cx = rect.x + rect.width / 2;
+    const cy = rect.y + rect.height / 2;
+    return cx >= win.x && cx <= win.x + win.w && cy >= win.y && cy <= win.y + win.h;
+}
+function area(win) {
+    return win.w * win.h;
+}
+/**
+ * 选"你框的那块属于哪个窗口"。
+ *
+ * 规则：layer 0（普通应用窗口）里，**包含选区中心**的那些，取面积最小的 ——
+ * 这样点在一个大窗口里的小对话框上，裁的是对话框而不是整个背景窗口。
+ */
+function pickWindow(wins, rect) {
+    const candidates = wins
+        .filter((w) => w.layer === 0 && contains(w, rect))
+        .sort((a, b) => area(a) - area(b));
+    return candidates[0] || null;
+}
+/**
+ * 截一整块显示器（`screencapture -D`）。
+ *
+ * 为什么不用 `-R`：副屏在主屏左边时坐标是负的，`screencapture -R` 直接
+ * "could not create image from rect"；屏幕锁定时 `-R` 也会失败，而 `-D` 仍然可用。
+ * 所以统一按显示器截，再用 sips 裁到需要的矩形。
+ */
+async function captureDisplay(display, options, fileName) {
+    const dir = await ensureTmpDir();
+    const path = join(dir, fileName);
+    const index = display.index > 0 ? display.index : display.main ? 1 : 2;
+    await run(CAPTURE, ['-x', '-D', String(index), path]);
+    const size = await pngSize(path);
+    if (!size || display.w <= 0 || display.h <= 0) {
+        await rm(path, { force: true }).catch(() => { });
+        return null;
+    }
+    // 截错屏时宽高比通常对不上：宁可退回选区，也不要把红框画到一张不相干的图上
+    const expected = display.w / display.h;
+    const actual = size.w / size.h;
+    if (Math.abs(actual - expected) > expected * 0.02) {
+        await rm(path, { force: true }).catch(() => { });
+        return null;
+    }
+    return { path, size, scale: size.w / display.w };
+}
+/** 把显示器图按像素矩形裁出来（sips 的 --cropOffset 是 top left）。 */
+async function cropPng(source, box, size, out) {
+    const left = Math.max(0, Math.min(size.w - 1, Math.round(box.left)));
+    const top = Math.max(0, Math.min(size.h - 1, Math.round(box.top)));
+    const width = Math.max(1, Math.min(size.w - left, Math.round(box.width)));
+    const height = Math.max(1, Math.min(size.h - top, Math.round(box.height)));
+    await run('/usr/bin/sips', ['-c', String(height), String(width), '--cropOffset', String(top), String(left), source, '--out', out], 20_000);
+    const cropped = await pngSize(out);
+    return cropped ? { left, top, width: cropped.w, height: cropped.h } : null;
+}
+/** 截一块选区本身（没有 region 文件时的兜底 / 自动化测试用）。 */
+async function captureSelectionToFile(selection, options, fileName) {
+    const displays = prefetchedDisplays || (await listDisplays());
+    prefetchedDisplays = null;
+    const display = pickDisplay(displays, selection);
+    if (!display)
+        return null;
+    const dir = await ensureTmpDir();
+    const captured = await captureDisplay(display, options, `display-${options.seq}.png`);
+    if (!captured)
+        return null;
+    const box = {
+        left: (selection.x - display.x) * captured.scale,
+        top: (selection.y - display.y) * captured.scale,
+        width: selection.width * captured.scale,
+        height: selection.height * captured.scale,
+    };
+    const path = join(dir, fileName);
+    const crop = await cropPng(captured.path, box, captured.size, path);
+    await rm(captured.path, { force: true }).catch(() => { });
+    if (!crop)
+        return null;
+    return { path, size: { w: crop.width, h: crop.height }, scale: captured.scale };
+}
+function notifyWaiters() {
+    while (waiters.length > 0) {
+        const fn = waiters.shift();
+        if (fn)
+            fn();
+    }
+}
+async function publish(shot, shotSeq, note = '') {
+    state.total += 1;
+    state.lastError = note;
+    state.pending = shot;
+    // 成功这一次比之前那条失败更新：不要把旧错误再塞给客户端
+    state.pendingError = null;
+    state.lastShot = shot;
+    state.capturing = false;
+    notifyWaiters();
+    // 旧图已经没用了：客户端取图后就不再回头，保留最近几张只为重试与诊断
+    void pruneShots(shotSeq);
+}
+/**
+ * 截图失败（**起完截图之后**发生的失败）：把一条人话放进长轮询，客户端弹提示。
+ *
+ * 用户按 Esc 取消不算失败 —— 那条路径不调用这里。
+ */
+function fail(code, message) {
+    state.lastError = code;
+    state.pendingError = { code, message, at: Date.now() };
+    state.capturing = false;
+    notifyWaiters();
+}
+/** 删除 seq 之前的旧临时图（只删本插件自己的命名，不动目录里的其它东西）。 */
+async function pruneShots(currentSeq) {
+    try {
+        const dir = tmpDir();
+        const names = await readdir(dir);
+        for (const name of names) {
+            const match = /^(?:region|shot|display)-(\d+)\.png$/.exec(name);
+            if (!match)
+                continue;
+            if (Number(match[1]) <= currentSeq - KEEP_SHOTS) {
+                await rm(join(dir, name), { force: true }).catch(() => { });
+            }
+        }
+    }
+    catch {
+        /* 清不掉不影响功能 */
+    }
+}
+/**
+ * 仅选区：框选落下的 region 文件**就是**最终图。
+ *
+ * 不需要窗口列表、不需要 xattr、不需要第二次截图；客户端也不用画布。
+ */
+async function finishSelection(regionFile, selection, options, note = '') {
+    const size = await pngSize(regionFile);
+    if (!size) {
+        fail('image-missing', '截图已经拍下，但读不到图片文件，请重试');
+        return;
+    }
+    const sel = selection || { x: 0, y: 0, width: size.w, height: size.h };
+    const scale = sel.width > 0 ? size.w / sel.width : 1;
+    const shot = {
+        id: `shot-${options.seq}`,
+        at: Date.now(),
+        scope: 'selection',
+        mode: options.mode,
+        frame: false,
+        imagePath: regionFile,
+        rect: { x: 0, y: 0, width: size.w, height: size.h },
+        windowRect: sel,
+        selectionRect: sel,
+        scale,
+        pad: { x: 0, y: 0 },
+        owner: '',
+        ready: true,
+    };
+    await publish(shot, options.seq, note);
+}
+/** 回退到「仅选区」：有 region 就用它，没有就现截一块。 */
+async function fallbackSelection(selection, options, regionFile, note) {
+    if (regionFile)
+        return finishSelection(regionFile, selection, options, note);
+    const captured = await captureSelectionToFile(selection, options, `region-${options.seq}.png`);
+    if (captured)
+        return finishSelection(captured.path, selection, options, note);
+    fail(note || 'selection-failed', '截图已拍下，但读取图片失败，请重试');
+}
+/** 选区 + 留白：外扩后裁到选区中心所在的那块屏，再从整屏图里裁出来。 */
+async function finishMargin(selection, options, regionFile, note = '') {
+    const margin = Math.max(0, Math.min(MAX_MARGIN_PT, Math.round(options.margin)));
+    if (margin <= 0)
+        return fallbackSelection(selection, options, regionFile, note);
+    let expanded = {
+        x: selection.x - margin,
+        y: selection.y - margin,
+        width: selection.width + margin * 2,
+        height: selection.height + margin * 2,
+    };
+    const displays = prefetchedDisplays || (await listDisplays());
+    prefetchedDisplays = null;
+    const display = pickDisplay(displays, selection);
+    if (!display)
+        return fallbackSelection(selection, options, regionFile, note || 'no-display');
+    expanded = clampRect(expanded, display);
+    if (expanded.width < 2 || expanded.height < 2) {
+        return fallbackSelection(selection, options, regionFile, note || 'margin-clipped');
+    }
+    const captured = await captureDisplay(display, options, `display-${options.seq}.png`);
+    if (!captured) {
+        return fallbackSelection(selection, options, regionFile, note || 'margin-capture-failed');
+    }
+    const scale = captured.scale;
+    const dir = await ensureTmpDir();
+    const imagePath = join(dir, `shot-${options.seq}.png`);
+    const crop = await cropPng(captured.path, {
+        left: (expanded.x - display.x) * scale,
+        top: (expanded.y - display.y) * scale,
+        width: expanded.width * scale,
+        height: expanded.height * scale,
+    }, captured.size, imagePath);
+    await rm(captured.path, { force: true }).catch(() => { });
+    if (!crop) {
+        return fallbackSelection(selection, options, regionFile, note || 'margin-crop-failed');
+    }
+    const shot = {
+        id: `shot-${options.seq}`,
+        at: Date.now(),
+        scope: 'margin',
+        mode: options.mode,
+        frame: true,
+        imagePath,
+        rect: {
+            // 用裁切后的实际像素原点，避免 sips 取整带来的 1px 偏移
+            x: Math.round((selection.x - display.x) * scale) - crop.left,
+            y: Math.round((selection.y - display.y) * scale) - crop.top,
+            width: Math.round(selection.width * scale),
+            height: Math.round(selection.height * scale),
+        },
+        windowRect: expanded,
+        selectionRect: selection,
+        scale,
+        pad: { x: 0, y: 0 },
+        owner: '',
+        ready: true,
+    };
+    await publish(shot, options.seq, note);
+}
+/** 全屏：选区中心所在的那块显示器整屏截下来。 */
+async function finishScreen(selection, options, regionFile) {
+    const displays = prefetchedDisplays || (await listDisplays());
+    prefetchedDisplays = null;
+    const display = pickDisplay(displays, selection);
+    if (!display) {
+        state.lastError = 'no-display';
+        return finishMargin(selection, options, regionFile, 'no-display');
+    }
+    const captured = await captureDisplay(display, options, `shot-${options.seq}.png`);
+    if (!captured) {
+        state.lastError = 'screen-capture-failed';
+        return finishMargin(selection, options, regionFile, 'screen-capture-failed');
+    }
+    const scale = captured.scale;
+    const shot = {
+        id: `shot-${options.seq}`,
+        at: Date.now(),
+        scope: 'screen',
+        mode: options.mode,
+        frame: true,
+        imagePath: captured.path,
+        rect: {
+            x: Math.round((selection.x - display.x) * scale),
+            y: Math.round((selection.y - display.y) * scale),
+            width: Math.round(selection.width * scale),
+            height: Math.round(selection.height * scale),
+        },
+        windowRect: { x: display.x, y: display.y, width: display.w, height: display.h },
+        selectionRect: selection,
+        scale,
+        pad: { x: 0, y: 0 },
+        owner: '',
+        ready: true,
+    };
+    await publish(shot, options.seq);
+}
+/** 整窗：找窗口、整窗截图；找不到或探针缺失时退到「选区 + 留白」。 */
+async function finishWindow(regionFile, selection, options) {
+    if (!(await probeAvailable())) {
+        state.lastError = 'probe-missing';
+        return finishMargin(selection, options, regionFile, 'probe-missing');
+    }
+    const wins = prefetchedWindows || (await listWindows());
+    prefetchedWindows = null;
+    const win = pickWindow(wins, selection);
+    if (!win) {
+        state.lastError = 'no-window';
+        return finishMargin(selection, options, regionFile, 'no-window');
+    }
+    const dir = await ensureTmpDir();
+    const imagePath = join(dir, `shot-${options.seq}.png`);
+    // ⚠️ 不要加 `-o`：文档说它"不截窗口阴影"，实测**反过来** ——
+    // 加了是 3840×2224（多 64px 阴影），不加才是 3840×2160（正好窗口的 2 倍）。
+    // 阴影上下不对称，按对半分会让红框整体偏（用户实测：向上偏移）。
+    await run(CAPTURE, ['-l', String(win.id), '-x', imagePath]);
+    const size = await pngSize(imagePath);
+    if (!size) {
+        state.lastError = 'window-capture-failed';
+        return finishMargin(selection, options, regionFile, 'window-capture-failed');
+    }
+    const scale = win.w > 0 ? size.w / win.w : 2;
+    const windowRect = { x: win.x, y: win.y, width: win.w, height: win.h };
+    // 正常情况 size 应当正好等于窗口的倍数（pad=0）；万一系统还是带了阴影，
+    // 就按"多出来的两半分"兜底 —— 客户端的 alpha 内容区探测会再校正一次。
+    const pad = {
+        x: Math.max(0, Math.round((size.w - win.w * scale) / 2)),
+        y: Math.max(0, Math.round((size.h - win.h * scale) / 2)),
+    };
+    const shot = {
+        id: `shot-${options.seq}`,
+        at: Date.now(),
+        scope: 'window',
+        mode: options.mode,
+        frame: true,
+        imagePath,
+        rect: {
+            x: Math.round(pad.x + (selection.x - windowRect.x) * scale),
+            y: Math.round(pad.y + (selection.y - windowRect.y) * scale),
+            width: Math.round(selection.width * scale),
+            height: Math.round(selection.height * scale),
+        },
+        windowRect,
+        selectionRect: selection,
+        scale,
+        pad,
+        owner: win.owner,
+        ready: true,
+    };
+    await publish(shot, options.seq);
+}
+/**
+ * 用户松手后的分派。
+ *
+ * 顺序仍然刻意：**先出图，后发事件**。UI 一旦画出来，`screencapture` 就会把它截进去
+ * （框、卡片都算页面内容）。仅选区的图在框选时就已经落好了，没有这个顾虑。
+ */
+async function finishInteractive(regionFile, options, knownRect) {
+    let selection = knownRect || null;
+    if (!selection && options.scope !== 'selection') {
+        selection = await rectFromXattr(regionFile);
+    }
+    if (options.scope === 'selection') {
+        const rect = selection || (await rectFromXattr(regionFile));
+        return finishSelection(regionFile, rect, options);
+    }
+    if (!selection) {
+        state.lastError = 'no-rect';
+        return finishSelection(regionFile, null, options, 'no-rect');
+    }
+    switch (options.scope) {
+        case 'margin':
+            return finishMargin(selection, options, regionFile);
+        case 'screen':
+            return finishScreen(selection, options, regionFile);
+        case 'window':
+        default:
+            return finishWindow(regionFile, selection, options);
+    }
+}
+/** 把 screencapture 的 stderr 翻成用户能照做的一句话。 */
+function friendlyCaptureError(stderr, code) {
+    const text = stderr.toLowerCase();
+    if (text.includes('not authorized') || text.includes('permission') || text.includes('could not create image')) {
+        return '没有屏幕录制权限：请在 系统设置 → 隐私与安全性 → 屏幕录制 中允许 DSH，然后重试';
+    }
+    const tail = stderr.trim().replace(/\s+/g, ' ').slice(0, 160);
+    return `系统截图失败（退出码 ${code ?? '未知'}）${tail ? `：${tail}` : ''}`;
+}
+/** 起一次交互式框选。 */
+async function startInteractive(options) {
+    if (!ensureCaptureAvailable())
+        return false;
+    if (state.capturing)
+        return false;
+    state.capturing = true;
+    const shotSeq = ++seq;
+    const opts = { ...options, seq: shotSeq };
+    let dir;
+    try {
+        dir = await ensureTmpDir();
+    }
+    catch (error) {
+        state.lastError = `tmp-failed: ${String(error?.message ?? error)}`;
+        state.capturing = false;
+        return false;
+    }
+    const regionFile = join(dir, `region-${shotSeq}.png`);
+    await rm(regionFile, { force: true }).catch(() => { });
+    // 和框选并行：用户拖框那一两秒里，窗口 / 显示器列表早就拿好了
+    prefetchedWindows = null;
+    prefetchedDisplays = null;
+    if (opts.scope === 'window') {
+        void listWindows()
+            .then((wins) => {
+            prefetchedWindows = wins;
+        })
+            .catch(() => { });
+    }
+    if (opts.scope !== 'selection') {
+        void listDisplays()
+            .then((displays) => {
+            prefetchedDisplays = displays;
+        })
+            .catch(() => { });
+    }
+    const child = spawn(CAPTURE, ['-i', '-x', regionFile], { stdio: ['ignore', 'ignore', 'pipe'] });
+    let stderr = '';
+    let timedOut = false;
+    child.stderr?.on('data', (chunk) => {
+        if (stderr.length < 4000)
+            stderr += String(chunk);
+    });
+    const timer = setTimeout(() => {
+        timedOut = true;
+        try {
+            child.kill('SIGTERM');
+        }
+        catch {
+            /* already gone */
+        }
+    }, SELECT_TIMEOUT_MS);
+    unrefTimer(timer);
+    child.on('error', () => {
+        clearTimeout(timer);
+        fail('spawn-failed', '无法启动系统截图命令（screencapture）');
+    });
+    child.on('close', (code, signal) => {
+        clearTimeout(timer);
+        // stat 失败（没有文件）不等于程序异常：先当成"没拍到"，下面按退出码/stderr 区分
+        void stat(regionFile)
+            .catch(() => null)
+            .then((s) => {
+            // spawn 失败已经报过（'error' 之后仍可能来一条 close）
+            if (state.pendingError)
+                return undefined;
+            if (s && s.size > 0)
+                return finishInteractive(regionFile, opts);
+            if (timedOut || signal === 'SIGTERM') {
+                fail('timeout', '框选超时，已取消这次截图');
+            }
+            else if ((typeof code === 'number' && code !== 0) || stderr.trim()) {
+                // 非 0 退出码或 stderr 都说明系统截图失败；退出码 0 + 无输出才是用户按 Esc
+                fail('capture-failed', friendlyCaptureError(stderr, code));
+            }
+            return undefined;
+        })
+            .catch((error) => {
+            // 已经发布过结果（例如回退成功）就不要再追加一条失败
+            const shotId = `shot-${shotSeq}`;
+            if (state.pending?.id === shotId || state.lastShot?.id === shotId)
+                return;
+            const message = String(error?.message ?? error);
+            fail('finish-failed', `截图已拍下，但处理失败：${message}`);
+        })
+            .finally(() => {
+            state.capturing = false;
+            prefetchedWindows = null;
+            prefetchedDisplays = null;
+        });
+    });
+    return true;
+}
+/** 开发/自动化用：跳过交互式框选，直接按给定矩形截一块再走同一条收尾流程。 */
+async function startWithRect(rect, options) {
+    if (!ensureCaptureAvailable())
+        return false;
+    if (state.capturing)
+        return false;
+    state.capturing = true;
+    const shotSeq = ++seq;
+    const opts = { ...options, seq: shotSeq };
+    // 自动化路径也用"整屏 + 裁切"，与真实框选走出同一套坐标：不再依赖 `-R`
+    try {
+        const captured = await captureSelectionToFile(rect, opts, `region-${shotSeq}.png`);
+        if (!captured) {
+            state.capturing = false;
+            state.lastError = 'capture-failed';
+            return false;
+        }
+        await finishInteractive(captured.path, opts, rect);
+        return true;
+    }
+    catch (error) {
+        state.lastError = `start-failed: ${String(error?.message ?? error)}`;
+        return false;
+    }
+    finally {
+        state.capturing = false;
+    }
+}
+const DEFAULT_SHOT_CONFIG = {
+    shotCardScope: 'window',
+    shotPanelScope: 'selection',
+    shotMargin: 48,
+};
+function resolveOptions(config, mode, url) {
+    const override = url.searchParams.get('scope');
+    const stored = mode === 'panel' ? config.shotPanelScope : config.shotCardScope;
+    const raw = override && SHOT_SCOPES.includes(override) ? override : stored;
+    const scope = SHOT_SCOPES.includes(raw) ? raw : mode === 'panel' ? 'selection' : 'window';
+    const marginParam = url.searchParams.get('margin');
+    const marginValue = marginParam === null ? NaN : Number(marginParam);
+    const fallback = Number.isFinite(config.shotMargin) ? config.shotMargin : 48;
+    const margin = Number.isFinite(marginValue)
+        ? Math.max(0, Math.min(MAX_MARGIN_PT, Math.round(marginValue)))
+        : Math.max(0, Math.min(MAX_MARGIN_PT, Math.round(fallback)));
+    return { mode, scope, margin };
+}
+/** `POST /api/shot/start` —— 开始一次截图（可带 `?rect=x,y,w,h&scope=…` 供测试）。 */
+export async function handleShotStart(req, res, config = DEFAULT_SHOT_CONFIG) {
+    if (req.method !== 'POST') {
+        sendJson(res, 405, { ok: false, reason: 'method-not-allowed' });
+        return;
+    }
+    // 新的一次尝试覆盖上一次还没取走的失败提示
+    state.pendingError = null;
+    const url = new URL(req.url || '/', 'http://localhost');
+    const rectParam = url.searchParams.get('rect');
+    const mode = url.searchParams.get('mode') === 'panel' ? 'panel' : 'card';
+    try {
+        await readBody(req, 64 * 1024).catch(() => '');
+    }
+    catch {
+        /* 没有 body 也无所谓 */
+    }
+    if (!ensureCaptureAvailable()) {
+        sendJson(res, 200, { ok: false, reason: state.reason });
+        return;
+    }
+    if (state.capturing) {
+        sendJson(res, 200, { ok: false, reason: 'busy' });
+        return;
+    }
+    const options = resolveOptions(config, mode, url);
+    if (rectParam) {
+        const n = rectParam.split(',').map(Number);
+        if (n.length === 4 && n.every(Number.isFinite) && n[2] > 0 && n[3] > 0) {
+            const started = await startWithRect({ x: n[0], y: n[1], width: n[2], height: n[3] }, options);
+            sendJson(res, 200, {
+                ok: started,
+                test: true,
+                mode,
+                scope: options.scope,
+                margin: options.margin,
+                ...(started ? {} : { reason: state.lastError || 'start-failed' }),
+            });
+            return;
+        }
+    }
+    const started = await startInteractive(options);
+    sendJson(res, 200, {
+        ok: started,
+        mode,
+        scope: options.scope,
+        margin: options.margin,
+        ...(started ? {} : { reason: state.lastError || 'start-failed' }),
+    });
+}
+/** `GET /api/shot/pending` —— 长轮询，等下一次截图结果或失败原因（最多 25 秒）。 */
+export function handleShotPending(_req, res) {
+    const takeShot = () => {
+        const shot = state.pending;
+        state.pending = null;
+        return shot;
+    };
+    const takeError = () => {
+        const error = state.pendingError;
+        state.pendingError = null;
+        return error;
+    };
+    const reply = () => {
+        sendJson(res, 200, { ok: true, shot: takeShot(), error: takeError(), status: shotStatus() });
+    };
+    if (state.pending || state.pendingError) {
+        reply();
+        return;
+    }
+    const timer = setTimeout(() => {
+        const i = waiters.indexOf(done);
+        if (i >= 0)
+            waiters.splice(i, 1);
+        reply();
+    }, 25_000);
+    // 长轮询只是"等客户端结果"，绝不能把一个挂着它的 Host 进程钉在事件循环里：
+    // 桌面端更新/退出只给 Host 10 秒优雅期限，未 unref 的 25s 定时器会让外壳判定
+    // "Host did not complete graceful task teardown" 并拒绝安装更新。
+    unrefTimer(timer);
+    const done = () => {
+        clearTimeout(timer);
+        reply();
+    };
+    waiters.push(done);
+}
+/** `GET /api/shot/image?id=` —— 把图按字节回给客户端（不进 JSON，避免几 MB 的 base64）。 */
+export async function handleShotImage(req, res) {
+    const url = new URL(req.url || '/', 'http://localhost');
+    const id = url.searchParams.get('id') || '';
+    const shot = state.pending && state.pending.id === id
+        ? state.pending
+        : state.lastShot && state.lastShot.id === id
+            ? state.lastShot
+            : null;
+    if (!shot) {
+        res.statusCode = 404;
+        res.end('shot-not-found');
+        return;
+    }
+    // 图已经落盘（ready 恒为 true）；保留这段等待是为了兼容"先发事件、后出图"的未来实现
+    const deadline = Date.now() + 4000;
+    while (!shot.ready && Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 50));
+    }
+    if (!shot.ready) {
+        res.statusCode = 404;
+        res.end('not-ready');
+        return;
+    }
+    try {
+        const buf = await readFile(shot.imagePath);
+        res.statusCode = 200;
+        res.setHeader('content-type', 'image/png');
+        res.setHeader('cache-control', 'no-store');
+        res.end(buf);
+    }
+    catch {
+        res.statusCode = 500;
+        res.end('read-failed');
+    }
+}
+/** 客户端加载时回报的自检结果（开发期用，只存内存）。 */
+export let clientHello = null;
+/** 按 stage 保留最近一次上报：'geometry' 这种关键诊断不会被后面的 'uploaded' 覆盖。 */
+export const clientReports = {};
+export function handleShotHello(req, res) {
+    const chunks = [];
+    req.on('data', (c) => chunks.push(c));
+    req.on('end', () => {
+        try {
+            clientHello = JSON.parse(Buffer.concat(chunks).toString('utf8') || 'null');
+            const stage = clientHello?.stage;
+            if (stage)
+                clientReports[stage] = clientHello;
+        }
+        catch {
+            clientHello = { parseError: true };
+        }
+        sendJson(res, 200, { ok: true });
+    });
+}
+export function shotStatus() {
+    return {
+        available: state.available,
+        reason: state.reason,
+        capturing: state.capturing,
+        total: state.total,
+        lastError: state.lastError,
+    };
+}
+/** 插件卸载 / 热重载：把临时目录清掉（截图是临时的，没有留着的理由）。 */
+export async function stopShot() {
+    try {
+        await rm(tmpDir(), { recursive: true, force: true });
+    }
+    catch {
+        /* 清不掉也不影响功能 */
+    }
+}
+/** `GET /api/shot/status` —— 调试/自检。 */
+export async function handleShotStatus(_req, res) {
+    ensureCaptureAvailable();
+    const probe = await probeAvailable();
+    const last = state.lastShot;
+    sendJson(res, 200, {
+        ok: true,
+        status: shotStatus(),
+        windowProbe: probe,
+        clientHello,
+        clientReports,
+        // 只读观察点：不清 pending，用来量"事件发出 → 图做好"这一段
+        lastShot: last
+            ? {
+                id: last.id,
+                scope: last.scope,
+                mode: last.mode,
+                frame: last.frame,
+                ready: last.ready,
+                ageMs: Date.now() - last.at,
+                owner: last.owner,
+                rect: last.rect,
+                pad: last.pad,
+                scale: last.scale,
+                selectionRect: last.selectionRect,
+                windowRect: last.windowRect,
+            }
+            : null,
+    });
+}
+//# sourceMappingURL=shot.js.map