Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

feat(desktop): 内置截图工具,直接交给 Cindy AI 任务,支持滚动截图、区域录屏和 GIF,不再依赖IM工具 (#7300)

DavidShenXDcdfec9aa5b8c
diff --git a/apps/desktop/forge.config.ts b/apps/desktop/forge.config.ts
index eef604af5b..ed78d34718 100644
--- a/apps/desktop/forge.config.ts
+++ b/apps/desktop/forge.config.ts
@@ -930,6 +930,7 @@ const MACOS_SESSION_DRAG_RELEASE_HELPER_DEPLOYMENT_TARGET = 'macos10.15';
const MACOS_MENUBAR_HELPER_DEPLOYMENT_TARGET = 'macos14.0';
const MACOS_XBOX_GAMEPAD_HELPER_DEPLOYMENT_TARGET = 'macos11.0';
const MACOS_REMOTE_DESKTOP_INPUT_DEPLOYMENT_TARGET = 'macos10.15';
+const MACOS_REGION_SCREENSHOT_HELPER_DEPLOYMENT_TARGET = 'macos10.15';
function swiftArchLabel(arch: ForgeArch, deploymentTarget: string): string {
return swiftTargetTriplesForForgeArch(arch, deploymentTarget)
@@ -1360,6 +1361,57 @@ function buildWindowsInputHelper(
fs.copyFileSync(path.join(source, 'target', target, 'release', name), path.join(dest, name));
}
+/**
+ * 框选截图的窗口 / 界面元素识别程序 (只产出几何信息)。Windows 用 Rust + UI
+ * Automation, macOS 用 Swift + CGWindowList / AX; 缺失时截图照常可用, 只是不吸附。
+ */
+function buildRegionScreenshotHelper(platform: ForgePlatform, arch: ForgeArch): void {
+ const dest = path.join(__dirname, 'resources', 'tools', 'region-screenshot');
+ if (process.platform === 'darwin' && isMacForgePlatform(platform)) {
+ const src = path.join(__dirname, 'native', 'region-screenshot', 'macos-snapshot.swift');
+ fs.mkdirSync(dest, { recursive: true });
+ const output = path.join(dest, 'cindy-macos-screenshot-snapshot');
+ buildSwiftHelperForForgeArch(
+ src,
+ output,
+ arch,
+ MACOS_REGION_SCREENSHOT_HELPER_DEPLOYMENT_TARGET,
+ ['-O'],
+ 'region screenshot snapshot helper',
+ );
+ fs.chmodSync(output, 0o755);
+ return;
+ }
+ if (process.platform !== 'win32' || platform !== 'win32') return;
+ const target =
+ arch === 'arm64' ? 'aarch64-pc-windows-msvc' : arch === 'x64' ? 'x86_64-pc-windows-msvc' : null;
+ if (!target) throw new Error(`[forge] Unsupported region screenshot helper architecture: ${arch}`);
+ const source = path.join(__dirname, 'native', 'region-screenshot', 'windows-snapshot');
+ const userCargo = process.env.USERPROFILE
+ ? path.join(process.env.USERPROFILE, '.cargo', 'bin', 'cargo.exe')
+ : 'cargo';
+ const result = spawnSync(
+ fs.existsSync(userCargo) ? userCargo : 'cargo',
+ [
+ 'build',
+ '--locked',
+ '--release',
+ '--target',
+ target,
+ '--manifest-path',
+ path.join(source, 'Cargo.toml'),
+ ],
+ { stdio: 'inherit', windowsHide: true },
+ );
+ if (result.error || result.status !== 0)
+ throw new Error(
+ `[forge] Region screenshot helper build failed: ${result.error?.message ?? result.status}`,
+ );
+ const name = 'cindy-windows-screenshot-snapshot.exe';
+ fs.mkdirSync(dest, { recursive: true });
+ fs.copyFileSync(path.join(source, 'target', target, 'release', name), path.join(dest, name));
+}
+
function buildMacXboxGamepadHelper(platform: ForgePlatform, arch: ForgeArch): void {
if (process.platform !== 'darwin' || !isMacForgePlatform(platform)) return;
const src = path.join(__dirname, 'native', 'xbox-gamepad', 'macos-xbox-gamepad-helper.swift');
@@ -1999,6 +2051,7 @@ const config: ForgeConfig = {
buildMacSessionDragReleaseHelper(platform, arch);
buildMacMenubarHelper(platform, arch);
buildRemoteDesktopInput(platform, arch);
+ buildRegionScreenshotHelper(platform, arch);
},
// packaged dir 产出后、makers 跑之前签内部 .exe。这样 NSIS 包出来的
// Setup.exe 内嵌的、和 publish 阶段从同一 packagedDir 打的热更 ZIP 内嵌的,
@@ -2175,6 +2228,27 @@ const config: ForgeConfig = {
config: 'vite.preload.config.ts',
target: 'preload',
},
+ {
+ // 全局框选截图浮层与贴图窗口: 各自只暴露截图的固定通道和只读外观快照。
+ entry: 'src/preload/regionScreenshotPreload.ts',
+ config: 'vite.preload.config.ts',
+ target: 'preload',
+ },
+ {
+ entry: 'src/preload/regionScreenshotPinPreload.ts',
+ config: 'vite.preload.config.ts',
+ target: 'preload',
+ },
+ {
+ entry: 'src/preload/regionScreenshotEditorPreload.ts',
+ config: 'vite.preload.config.ts',
+ target: 'preload',
+ },
+ {
+ entry: 'src/preload/recordingPreviewPreload.ts',
+ config: 'vite.preload.config.ts',
+ target: 'preload',
+ },
{
// 资源用量独立窗不加载主应用的通用 bridge 与模块级同步初始化。
entry: 'src/preload/resourceUsagePreload.ts',
diff --git a/apps/desktop/native/region-screenshot/macos-snapshot.swift b/apps/desktop/native/region-screenshot/macos-snapshot.swift
new file mode 100644
index 0000000000..89a7a727e4
--- /dev/null
+++ b/apps/desktop/native/region-screenshot/macos-snapshot.swift
@@ -0,0 +1,207 @@
+// Region screenshot snapshot helper (macOS).
+//
+// Same line protocol as the Windows helper (one JSON request per stdin line,
+// one JSON line back). Rectangles are global points [left, top, right, bottom]
+// with the origin at the top-left of the primary display, which is Electron's
+// DIP space.
+//
+// - {"id":1,"op":"windows"} on-screen windows, front to back (with owner pid).
+// - {"id":2,"op":"elements","pid":P,"x":X,"y":Y} accessibility elements of
+// that app under the point, innermost first. The tree is walked from the
+// app's windows instead of hit-testing the screen, because Cindy's overlay
+// covers the screen. Needs the Accessibility permission; without it the
+// answer is empty and the overlay snaps to windows only.
+// - {"id":3,"op":"frontmost"} / {"id":4,"op":"activate","pid":P} remember and
+// give focus back to the app the user was in before the screenshot.
+// - {"id":5,"op":"screens"} per display the top inset taken by the camera
+// housing (notch), also while the menu bar is hidden.
+//
+// Geometry, process ids and explicitly requested physical key labels only.
+
+import AppKit
+import ApplicationServices
+import Foundation
+
+let elementBudget: TimeInterval = 0.25
+let maxDepth = 40
+let minSide: CGFloat = 4
+/// Windows at or above the Dock level (Dock, menu bar, status items, Control
+/// Centre, cursor and shield windows) are system chrome, not snap targets.
+let maxSnapLayer = Int(CGWindowLevelForKey(.dockWindow))
+var elementDeadline: Date?
+
+func emit(_ object: [String: Any]) {
+ guard let data = try? JSONSerialization.data(withJSONObject: object),
+ let line = String(data: data, encoding: .utf8)
+ else { return }
+ FileHandle.standardOutput.write((line + "\n").data(using: .utf8)!)
+}
+
+func rectArray(_ rect: CGRect) -> [Double] {
+ [Double(rect.minX), Double(rect.minY), Double(rect.maxX), Double(rect.maxY)]
+}
+
+func onScreenWindows() -> [[String: Any]] {
+ let options: CGWindowListOption = [.optionOnScreenOnly, .excludeDesktopElements]
+ guard let list = CGWindowListCopyWindowInfo(options, kCGNullWindowID) as? [[String: Any]] else {
+ return []
+ }
+ var result: [[String: Any]] = []
+ for info in list {
+ let alpha = (info[kCGWindowAlpha as String] as? Double) ?? 1
+ if alpha <= 0.01 { continue }
+ let layer = (info[kCGWindowLayer as String] as? Int) ?? 0
+ if layer < 0 || layer >= maxSnapLayer { continue }
+ if (info[kCGWindowOwnerName as String] as? String) == "Window Server" { continue }
+ guard let bounds = info[kCGWindowBounds as String] as? NSDictionary,
+ let rect = CGRect(dictionaryRepresentation: bounds as CFDictionary),
+ rect.width >= minSide, rect.height >= minSide,
+ let number = info[kCGWindowNumber as String] as? Int,
+ let pid = info[kCGWindowOwnerPID as String] as? Int
+ else { continue }
+ result.append(["hwnd": number, "pid": pid, "rect": rectArray(rect)])
+ }
+ return result
+}
+
+func attribute(_ element: AXUIElement, _ name: String) -> CFTypeRef? {
+ if let deadline = elementDeadline {
+ let remaining = deadline.timeIntervalSinceNow
+ guard remaining > 0 else { return nil }
+ // AX 的超时是逐对象设置,应用对象上的值不会保护子元素调用。
+ AXUIElementSetMessagingTimeout(element, Float(min(0.05, remaining)))
+ }
+ var value: CFTypeRef?
+ guard AXUIElementCopyAttributeValue(element, name as CFString, &value) == .success else {
+ return nil
+ }
+ return value
+}
+
+func frame(of element: AXUIElement) -> CGRect? {
+ guard let position = attribute(element, kAXPositionAttribute),
+ let size = attribute(element, kAXSizeAttribute),
+ CFGetTypeID(position) == AXValueGetTypeID(), CFGetTypeID(size) == AXValueGetTypeID()
+ else { return nil }
+ var point = CGPoint.zero
+ var extent = CGSize.zero
+ guard AXValueGetValue(position as! AXValue, .cgPoint, &point),
+ AXValueGetValue(size as! AXValue, .cgSize, &extent)
+ else { return nil }
+ let rect = CGRect(origin: point, size: extent)
+ return rect.width >= minSide && rect.height >= minSide ? rect : nil
+}
+
+func children(of element: AXUIElement) -> [AXUIElement] {
+ (attribute(element, kAXChildrenAttribute) as? [AXUIElement]) ?? []
+}
+
+/// Smallest element among `candidates` whose frame contains the point.
+func smallest(_ candidates: [AXUIElement], containing point: CGPoint) -> (AXUIElement, CGRect)? {
+ var best: (AXUIElement, CGRect)?
+ for candidate in candidates {
+ if let deadline = elementDeadline, deadline <= Date() { break }
+ guard let rect = frame(of: candidate), rect.contains(point) else { continue }
+ if best == nil || rect.width * rect.height < best!.1.width * best!.1.height {
+ best = (candidate, rect)
+ }
+ }
+ return best
+}
+
+func elementChain(pid: pid_t, point: CGPoint) -> [[Double]] {
+ guard AXIsProcessTrusted() else { return [] }
+ let started = Date()
+ elementDeadline = started.addingTimeInterval(elementBudget)
+ defer { elementDeadline = nil }
+ let app = AXUIElementCreateApplication(pid)
+ let windows = (attribute(app, kAXWindowsAttribute) as? [AXUIElement]) ?? []
+ guard var current = smallest(windows, containing: point) else { return [] }
+ var chain: [CGRect] = [current.1]
+ for _ in 0..<maxDepth {
+ if Date().timeIntervalSince(started) > elementBudget { break }
+ guard let next = smallest(children(of: current.0), containing: point) else { break }
+ if next.1 != chain.last { chain.append(next.1) }
+ current = next
+ }
+ return chain.reversed().map(rectArray)
+}
+
+func screenInsets() -> [[String: Any]] {
+ NSScreen.screens.compactMap { screen in
+ guard let number = screen.deviceDescription[NSDeviceDescriptionKey("NSScreenNumber")] as? NSNumber
+ else { return nil }
+ var top: CGFloat = 0
+ if #available(macOS 12.0, *) { top = screen.safeAreaInsets.top }
+ return ["id": number.uint32Value, "top": Double(top)]
+ }
+}
+
+setvbuf(stdout, nil, _IOLBF, 0)
+while let line = readLine() {
+ guard let data = line.data(using: .utf8),
+ let request = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any]
+ else { continue }
+ let id = request["id"] ?? NSNull()
+ switch request["op"] as? String {
+ case "scroll":
+ guard AXIsProcessTrusted(),
+ let pid = (request["pid"] as? NSNumber)?.int32Value,
+ let x = (request["x"] as? NSNumber)?.doubleValue,
+ let y = (request["y"] as? NSNumber)?.doubleValue,
+ let delta = (request["delta"] as? NSNumber)?.int32Value,
+ x.isFinite, y.isFinite, delta >= -120, delta < 0,
+ let source = CGEventSource(stateID: .combinedSessionState),
+ let event = CGEvent(scrollWheelEvent2Source: source, units: .pixel, wheelCount: 1, wheel1: delta, wheel2: 0, wheel3: 0)
+ else { emit(["id": id, "ok": false]); continue }
+ let point = CGPoint(x: x, y: y)
+ var hit: AXUIElement?
+ AXUIElementCopyElementAtPosition(AXUIElementCreateSystemWide(), Float(x), Float(y), &hit)
+ var hitPid: pid_t = 0
+ if let hit = hit { AXUIElementGetPid(hit, &hitPid) }
+ guard hitPid == pid else { emit(["id": id, "ok": false]); continue }
+ event.location = point
+ event.postToPid(pid)
+ emit(["id": id, "ok": true])
+ case "keys":
+ if !CGPreflightListenEventAccess() {
+ emit(["id": id, "keys": NSNull()])
+ continue
+ }
+ let labels: [(CGKeyCode, String)] = [
+ (55,"⌘"),(56,"⇧"),(58,"⌥"),(59,"⌃"),(36,"Return"),(48,"Tab"),(49,"Space"),(51,"Delete"),
+ (123,"←"),(124,"→"),(125,"↓"),(126,"↑"),
+ (0,"A"),(1,"S"),(2,"D"),(3,"F"),(4,"H"),(5,"G"),(6,"Z"),(7,"X"),(8,"C"),(9,"V"),
+ (11,"B"),(12,"Q"),(13,"W"),(14,"E"),(15,"R"),(16,"Y"),(17,"T"),
+ (18,"1"),(19,"2"),(20,"3"),(21,"4"),(22,"6"),(23,"5"),(25,"9"),(26,"7"),(28,"8"),(29,"0"),
+ (31,"O"),(32,"U"),(34,"I"),(35,"P"),(37,"L"),(38,"J"),(40,"K"),(45,"N"),(46,"M")
+ ]
+ emit(["id": id, "keys": Array(labels.filter { CGEventSource.keyState(.combinedSessionState, key: $0.0) }.prefix(8).map { $0.1 })])
+ case "windows":
+ emit(["id": id, "windows": onScreenWindows()])
+ case "screens":
+ emit(["id": id, "screens": screenInsets()])
+ case "elements":
+ if let pid = (request["pid"] as? NSNumber)?.int32Value,
+ let x = (request["x"] as? NSNumber)?.doubleValue,
+ let y = (request["y"] as? NSNumber)?.doubleValue
+ {
+ emit(["id": id, "rects": elementChain(pid: pid, point: CGPoint(x: x, y: y))])
+ } else {
+ emit(["id": id, "error": "invalid-request"])
+ }
+ case "frontmost":
+ let pid = NSWorkspace.shared.frontmostApplication?.processIdentifier
+ emit(["id": id, "pid": pid.map { Int($0) } ?? NSNull()])
+ case "activate":
+ if let pid = (request["pid"] as? NSNumber)?.int32Value,
+ let app = NSRunningApplication(processIdentifier: pid)
+ {
+ emit(["id": id, "ok": app.activate(options: [])])
+ } else {
+ emit(["id": id, "ok": false])
+ }
+ default:
+ emit(["id": id, "error": "unknown-op"])
+ }
+}
diff --git a/apps/desktop/native/region-screenshot/windows-snapshot/.gitignore b/apps/desktop/native/region-screenshot/windows-snapshot/.gitignore
new file mode 100644
index 0000000000..b83d22266a
--- /dev/null
+++ b/apps/desktop/native/region-screenshot/windows-snapshot/.gitignore
@@ -0,0 +1 @@
+/target/
diff --git a/apps/desktop/native/region-screenshot/windows-snapshot/Cargo.lock b/apps/desktop/native/region-screenshot/windows-snapshot/Cargo.lock
new file mode 100644
index 0000000000..9bc1b802a7
--- /dev/null
+++ b/apps/desktop/native/region-screenshot/windows-snapshot/Cargo.lock
@@ -0,0 +1,252 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "base64"
+version = "0.22.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
+
+[[package]]
+name = "cindy-windows-screenshot-snapshot"
+version = "0.1.0"
+dependencies = [
+ "base64",
+ "serde_json",
+ "windows",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "serde"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
+dependencies = [
+ "serde_core",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.154"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
+
+[[package]]
+name = "windows"
+version = "0.58.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dd04d41d93c4992d421894c18c8b43496aa748dd4c081bac0dc93eb0489272b6"
+dependencies = [
+ "windows-core",
+ "windows-targets",
+]
+
+[[package]]
+name = "windows-core"
+version = "0.58.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ba6d44ec8c2591c134257ce647b7ea6b20335bf6379a27dac5f1641fcf59f99"
+dependencies = [
+ "windows-implement",
+ "windows-interface",
+ "windows-result",
+ "windows-strings",
+ "windows-targets",
+]
+
+[[package]]
+name = "windows-implement"
+version = "0.58.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2bbd5b46c938e506ecbce286b6628a02171d56153ba733b6c741fc627ec9579b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "windows-interface"
+version = "0.58.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "053c4c462dc91d3b1504c6fe5a726dd15e216ba718e84a0e46a88fbe5ded3515"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "windows-result"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d1043d8214f791817bab27572aaa8af63732e11bf84aa21a45a78d6c317ae0e"
+dependencies = [
+ "windows-targets",
+]
+
+[[package]]
+name = "windows-strings"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4cd9b125c486025df0eabcb585e62173c6c9eddcec5d117d3b6e8c30e2ee4d10"
+dependencies = [
+ "windows-result",
+ "windows-targets",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
+dependencies = [
+ "windows_aarch64_gnullvm",
+ "windows_aarch64_msvc",
+ "windows_i686_gnu",
+ "windows_i686_gnullvm",
+ "windows_i686_msvc",
+ "windows_x86_64_gnu",
+ "windows_x86_64_gnullvm",
+ "windows_x86_64_msvc",
+]
+
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
+
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
+
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
+
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
diff --git a/apps/desktop/native/region-screenshot/windows-snapshot/Cargo.toml b/apps/desktop/native/region-screenshot/windows-snapshot/Cargo.toml
new file mode 100644
index 0000000000..fb83200766
--- /dev/null
+++ b/apps/desktop/native/region-screenshot/windows-snapshot/Cargo.toml
@@ -0,0 +1,25 @@
+[package]
+name = "cindy-windows-screenshot-snapshot"
+version = "0.1.0"
+edition = "2021"
+license = "Apache-2.0"
+
+[dependencies]
+serde_json = "1"
+base64 = "0.22"
+windows = { version = "0.58", features = [
+ "Win32_Foundation",
+ "Win32_Graphics_Dwm",
+ "Win32_Graphics_Gdi",
+ "Win32_System_Com",
+ "Win32_UI_Accessibility",
+ "Win32_UI_HiDpi",
+ "Win32_UI_Input_KeyboardAndMouse",
+ "Win32_UI_WindowsAndMessaging",
+] }
+
+[profile.release]
+panic = "abort"
+lto = true
+opt-level = "s"
+strip = true
diff --git a/apps/desktop/native/region-screenshot/windows-snapshot/src/main.rs b/apps/desktop/native/region-screenshot/windows-snapshot/src/main.rs
new file mode 100644
index 0000000000..51c6dc53e7
--- /dev/null
+++ b/apps/desktop/native/region-screenshot/windows-snapshot/src/main.rs
@@ -0,0 +1,297 @@
+//! Region screenshot snapshot helper (Windows).
+//!
+//! Long-lived during one screenshot: reads one JSON request per stdin line and
+//! answers with one JSON line on stdout. All rectangles are physical screen
+//! pixels `[left, top, right, bottom]` (the process is per-monitor DPI aware),
+//! Electron converts them to DIP.
+//!
+//! - `{"id":1,"op":"windows"}` → visible top-level windows, top of the z-order
+//! first, using the DWM frame (without the invisible resize border).
+//! - `{"id":2,"op":"elements","hwnd":N,"x":X,"y":Y}` → UI Automation elements of
+//! that window under the point, innermost first. The window is located from
+//! the snapshot instead of hit-testing the screen, because Cindy's overlay
+//! covers the screen while the user moves the cursor.
+//!
+//! Geometry plus explicitly requested physical key labels; no window titles or text fields.
+
+use std::io::{self, BufRead, Write};
+use std::time::{Duration, Instant};
+
+use serde_json::{json, Value};
+use base64::{engine::general_purpose::STANDARD, Engine};
+use windows::Win32::Graphics::Gdi::*;
+use windows::{
+ core::Interface,
+ Win32::{
+ Foundation::{BOOL, HWND, LPARAM, RECT, POINT, WPARAM},
+ Graphics::Dwm::{DwmGetWindowAttribute, DWMWA_CLOAKED, DWMWA_EXTENDED_FRAME_BOUNDS},
+ System::Com::{CoCreateInstance, CoInitializeEx, CLSCTX_INPROC_SERVER, COINIT_MULTITHREADED},
+ UI::{
+ Accessibility::*,
+ Input::KeyboardAndMouse::GetAsyncKeyState,
+ HiDpi::{SetProcessDpiAwarenessContext, DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2},
+ WindowsAndMessaging::{
+ EnumWindows, GetWindowLongW, GetWindowRect, IsIconic, IsWindowVisible, GWL_EXSTYLE,
+ WS_EX_TRANSPARENT, WindowFromPoint, GetAncestor, GA_ROOT, PostMessageW, WM_MOUSEWHEEL,
+ },
+ },
+ },
+};
+
+/// Upper bound for one element query; a slow or hung application must not
+/// stall the overlay. The caller keeps the last good answer.
+const ELEMENT_BUDGET: Duration = Duration::from_millis(250);
+const MAX_DEPTH: usize = 40;
+const MIN_SIDE: i32 = 4;
+
+fn main() {
+ unsafe {
+ let _ = SetProcessDpiAwarenessContext(DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2);
+ let _ = CoInitializeEx(None, COINIT_MULTITHREADED);
+ }
+ let automation = create_automation();
+ let stdin = io::stdin();
+ let mut stdout = io::stdout().lock();
+ for line in stdin.lock().lines() {
+ let Ok(line) = line else { break };
+ let Ok(request) = serde_json::from_str::<Value>(&line) else { continue };
+ let id = request.get("id").cloned().unwrap_or(Value::Null);
+ let response = match request.get("op").and_then(Value::as_str) {
+ Some("scroll") => json!({ "id": id, "ok": scroll_region(&request) }),
+ Some("keys") => json!({ "id": id, "keys": pressed_keys() }),
+ Some("frame") => match capture_region(&request) {
+ Some((width, height, pixels)) => json!({ "id": id, "width": width, "height": height, "pixels": STANDARD.encode(pixels) }),
+ None => json!({ "id": id, "error": "capture-unavailable" }),
+ },
+ Some("windows") => json!({ "id": id, "windows": enumerate_windows() }),
+ Some("elements") => {
+ let hwnd = request.get("hwnd").and_then(Value::as_i64);
+ let x = request.get("x").and_then(Value::as_i64);
+ let y = request.get("y").and_then(Value::as_i64);
+ match (&automation, hwnd, x, y) {
+ (Some(automation), Some(hwnd), Some(x), Some(y)) => json!({
+ "id": id,
+ "rects": element_chain(automation, hwnd as isize, x as i32, y as i32),
+ }),
+ (None, ..) => json!({ "id": id, "rects": [] }),
+ _ => json!({ "id": id, "error": "invalid-request" }),
+ }
+ }
+ _ => json!({ "id": id, "error": "unknown-op" }),
+ };
+ if writeln!(stdout, "{response}").and_then(|_| stdout.flush()).is_err() {
+ break;
+ }
+ }
+}
+
+/// Only scroll the snapshotted source while it is still under the selected point.
+/// Posting to that window avoids moving the user's cursor or sending clicks/keys.
+fn scroll_region(request: &Value) -> bool {
+ let Some(handle) = request.get("hwnd").and_then(Value::as_i64) else { return false; };
+ let Some(x) = request.get("x").and_then(Value::as_i64).and_then(|n| i32::try_from(n).ok()) else { return false; };
+ let Some(y) = request.get("y").and_then(Value::as_i64).and_then(|n| i32::try_from(n).ok()) else { return false; };
+ let Some(delta) = request.get("delta").and_then(Value::as_i64).filter(|d| (-120..=-1).contains(d)) else { return false; };
+ unsafe {
+ let target = WindowFromPoint(POINT { x, y });
+ let expected = HWND(handle as isize as *mut _);
+ if target.0.is_null() || GetAncestor(target, GA_ROOT) != expected || !IsWindowVisible(expected).as_bool() { return false; }
+ let position = ((y as u32 & 0xffff) << 16) | (x as u32 & 0xffff);
+ PostMessageW(target, WM_MOUSEWHEEL, WPARAM(((delta as i16 as u16 as u32) << 16) as usize), LPARAM(position as isize)).is_ok()
+ }
+}
+
+fn pressed_keys() -> Vec<String> {
+ let mut result = Vec::new();
+ for (code, label) in [(0x11, "Ctrl"), (0x12, "Alt"), (0x10, "Shift"), (0x5b, "Win"),
+ (0x0d, "Enter"), (0x09, "Tab"), (0x20, "Space"), (0x08, "Backspace"),
+ (0x25, "←"), (0x26, "↑"), (0x27, "→"), (0x28, "↓"), (0x2e, "Delete")] {
+ if unsafe { GetAsyncKeyState(code) } < 0 { result.push(label.to_string()); }
+ }
+ for code in 0x30..=0x5a {
+ if (code <= 0x39 || code >= 0x41) && unsafe { GetAsyncKeyState(code) } < 0 {
+ result.push(char::from_u32(code as u32).unwrap().to_string());
+ }
+ }
+ for code in 0x70..=0x7b {
+ if unsafe { GetAsyncKeyState(code) } < 0 { result.push(format!("F{}", code - 0x70 + 1)); }
+ }
+ result.truncate(8);
+ result
+}
+
+/// Capture just the host-validated physical rectangle. GDI excludes the mouse;
+/// the renderer optionally adds its cursor overlay. Every GDI object is released.
+fn capture_region(request: &Value) -> Option<(i32, i32, Vec<u8>)> {
+ let x = i32::try_from(request.get("x")?.as_i64()?).ok()?;
+ let y = i32::try_from(request.get("y")?.as_i64()?).ok()?;
+ let width = i32::try_from(request.get("width")?.as_i64()?).ok()?;
+ let height = i32::try_from(request.get("height")?.as_i64()?).ok()?;
+ let edge = i32::try_from(request.get("edge")?.as_i64()?).ok()?;
+ if width <= 0 || height <= 0 || width > 32768 || height > 32768 || !(32..=32768).contains(&edge) { return None; }
+ let ratio = (edge as f64 / width.max(height) as f64).min(1.0);
+ let out_w = (width as f64 * ratio).round().max(1.0) as i32;
+ let out_h = (height as f64 * ratio).round().max(1.0) as i32;
+ if i64::from(out_w) * i64::from(out_h) > 32_000_000 { return None; }
+ unsafe {
+ let desktop = GetDC(HWND::default());
+ if desktop.0.is_null() { return None; }
+ let memory = CreateCompatibleDC(desktop);
+ if memory.0.is_null() { ReleaseDC(HWND::default(), desktop); return None; }
+ let mut info = BITMAPINFO::default();
+ info.bmiHeader.biSize = std::mem::size_of::<BITMAPINFOHEADER>() as u32;
+ info.bmiHeader.biWidth = out_w;
+ info.bmiHeader.biHeight = -out_h;
+ info.bmiHeader.biPlanes = 1;
+ info.bmiHeader.biBitCount = 32;
+ info.bmiHeader.biCompression = BI_RGB.0;
+ let mut pixels = std::ptr::null_mut();
+ let bitmap = CreateDIBSection(memory, &info, DIB_RGB_COLORS, &mut pixels, None, 0);
+ let result = if let Ok(bitmap) = bitmap {
+ let previous = SelectObject(memory, bitmap);
+ let _ = SetStretchBltMode(memory, HALFTONE);
+ let ok = StretchBlt(memory, 0, 0, out_w, out_h, desktop, x, y, width, height, SRCCOPY | CAPTUREBLT).as_bool();
+ let _ = GdiFlush();
+ let output = if ok && !pixels.is_null() {
+ let mut data = std::slice::from_raw_parts(pixels as *const u8, (out_w * out_h * 4) as usize).to_vec();
+ for pixel in data.chunks_exact_mut(4) { pixel[3] = 255; }
+ Some((out_w, out_h, data))
+ } else { None };
+ SelectObject(memory, previous);
+ let _ = DeleteObject(bitmap);
+ output
+ } else { None };
+ let _ = DeleteDC(memory);
+ ReleaseDC(HWND::default(), desktop);
+ result
+ }
+}
+
+fn create_automation() -> Option<IUIAutomation> {
+ unsafe {
+ // IUIAutomation2 lets us cap cross-process calls into unresponsive apps.
+ if let Ok(automation) =
+ CoCreateInstance::<_, IUIAutomation2>(&CUIAutomation8, None, CLSCTX_INPROC_SERVER)
+ {
+ let _ = automation.SetConnectionTimeout(100);
+ let _ = automation.SetTransactionTimeout(50);
+ return automation.cast().ok();
+ }
+ CoCreateInstance(&CUIAutomation, None, CLSCTX_INPROC_SERVER).ok()
+ }
+}
+
+fn rect_json(rect: &RECT) -> Value {
+ json!([rect.left, rect.top, rect.right, rect.bottom])
+}
+
+fn usable(rect: &RECT) -> bool {
+ rect.right - rect.left >= MIN_SIDE && rect.bottom - rect.top >= MIN_SIDE
+}
+
+fn window_rect(hwnd: HWND) -> Option<RECT> {
+ let mut rect = RECT::default();
+ let frame = unsafe {
+ DwmGetWindowAttribute(
+ hwnd,
+ DWMWA_EXTENDED_FRAME_BOUNDS,
+ &mut rect as *mut RECT as *mut _,
+ std::mem::size_of::<RECT>() as u32,
+ )
+ };
+ if frame.is_err() && unsafe { GetWindowRect(hwnd, &mut rect) }.is_err() {
+ return None;
+ }
+ usable(&rect).then_some(rect)
+}
+
+fn is_cloaked(hwnd: HWND) -> bool {
+ let mut cloaked: u32 = 0;
+ unsafe {
+ DwmGetWindowAttribute(
+ hwnd,
+ DWMWA_CLOAKED,
+ &mut cloaked as *mut u32 as *mut _,
+ std::mem::size_of::<u32>() as u32,
+ )
+ }
+ .is_ok()
+ && cloaked != 0
+}
+
+unsafe extern "system" fn collect_window(hwnd: HWND, data: LPARAM) -> BOOL {
+ let windows = &mut *(data.0 as *mut Vec<Value>);
+ if !IsWindowVisible(hwnd).as_bool() || IsIconic(hwnd).as_bool() || is_cloaked(hwnd) {
+ return true.into();
+ }
+ // Click-through windows (system overlays, notification layers) are never
+ // what the user points at; skipping them keeps snapping under them working.
+ if GetWindowLongW(hwnd, GWL_EXSTYLE) as u32 & WS_EX_TRANSPARENT.0 != 0 {
+ return true.into();
+ }
+ if let Some(rect) = window_rect(hwnd) {
+ windows.push(json!({ "hwnd": hwnd.0 as isize, "rect": rect_json(&rect) }));
+ }
+ true.into()
+}
+
+fn enumerate_windows() -> Vec<Value> {
+ let mut windows: Vec<Value> = Vec::new();
+ unsafe {
+ let _ = EnumWindows(Some(collect_window), LPARAM(&mut windows as *mut _ as isize));
+ }
+ windows
+}
+
+fn contains(rect: &RECT, x: i32, y: i32) -> bool {
+ x >= rect.left && x < rect.right && y >= rect.top && y < rect.bottom
+}
+
+fn area(rect: &RECT) -> i64 {
+ (rect.right - rect.left) as i64 * (rect.bottom - rect.top) as i64
+}
+
+/// Walks the control view from the window down, at each level taking the
+/// smallest child that contains the point. Returns innermost first.
+fn element_chain(automation: &IUIAutomation, hwnd: isize, x: i32, y: i32) -> Vec<Value> {
+ let started = Instant::now();
+ let mut chain: Vec<RECT> = Vec::new();
+ let mut walk = || -> windows::core::Result<()> {
+ unsafe {
+ let cache = automation.CreateCacheRequest()?;
+ cache.AddProperty(UIA_BoundingRectanglePropertyId)?;
+ let condition = automation.ControlViewCondition()?;
+ cache.SetTreeFilter(&condition)?;
+ let mut current = automation.ElementFromHandle(HWND(hwnd as *mut _))?;
+ for _ in 0..MAX_DEPTH {
+ if started.elapsed() > ELEMENT_BUDGET {
+ break;
+ }
+ let children = current.FindAllBuildCache(TreeScope_Children, &condition, &cache)?;
+ let mut best: Option<(i64, IUIAutomationElement, RECT)> = None;
+ for index in 0..children.Length()? {
+ if started.elapsed() > ELEMENT_BUDGET {
+ break;
+ }
+ let Ok(child) = children.GetElement(index) else { continue };
+ let Ok(rect) = child.CachedBoundingRectangle() else { continue };
+ if !usable(&rect) || !contains(&rect, x, y) {
+ continue;
+ }
+ let size = area(&rect);
+ if best.as_ref().map_or(true, |(best_size, ..)| size < *best_size) {
+ best = Some((size, child, rect));
+ }
+ }
+ let Some((_, child, rect)) = best else { break };
+ if chain.last() != Some(&rect) {
+ chain.push(rect);
+ }
+ current = child;
+ }
+ Ok(())
+ }
+ };
+ let _ = walk();
+ chain.iter().rev().map(rect_json).collect()
+}
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index ac1614ec68..fff0d08db8 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -147,6 +147,7 @@
"electron-window-state": "^5.0.3",
"exceljs": "^4.4.0",
"fix-path": "^5.0.0",
+ "gifenc": "1.0.3",
"gray-matter": "^4.0.3",
"harmonyos-sans-sc-webfont-splitted": "1.1.0",
"highlight.js": "^11.11.1",
diff --git a/apps/desktop/scripts/fixtures/region-capture/capture-fixture.tsx b/apps/desktop/scripts/fixtures/region-capture/capture-fixture.tsx
new file mode 100644
index 0000000000..ab1bb57b44
--- /dev/null
+++ b/apps/desktop/scripts/fixtures/region-capture/capture-fixture.tsx
@@ -0,0 +1,87 @@
+import { useMemo, useState } from 'react';
+import type { RegionScreenshotBitmap } from '../../../src/shared/regionScreenshot';
+import { mountPage } from '../../ui-page/harness';
+import { RecordingPreview } from '../../../src/renderer/features/region-screenshot/RecordingPreview';
+import { RegionScreenshotOverlay } from '../../../src/renderer/features/region-screenshot/RegionScreenshotOverlay';
+import { imageDataToBitmap, type RegionScreenshotOverlayBridge } from '../../../src/renderer/features/region-screenshot/bridge';
+import { recordingControlsBounds, scrollCaptureLayout, type RecordingPreviewDocument, type RegionCaptureMode } from '../../../src/shared/regionCapture';
+
+const qa = { frames: 0, firstFrameAt: 0, keysRequested: false, closed: false, copyAttempts: 0, copied: false, scrollFrames: 0, scrollLimit: 180, manualScroll: null as number | null, idle: false, automatic: false, saved: null as Uint8Array | null, saveAttempts: 0, format: '', exportedHeight: 0, annotationPixels: 0, restored: false };
+Object.assign(window, { captureQa: qa });
+
+function frame(scroll = 0) {
+ const canvas = document.createElement('canvas');
+ canvas.width = 480; canvas.height = 240;
+ const context = canvas.getContext('2d')!;
+ context.fillStyle = '#f8f8f6'; context.fillRect(0, 0, 480, 240);
+ context.font = '16px sans-serif';
+ for (let row = 0; row < 30; row++) {
+ const y = row * 30 - scroll;
+ context.fillStyle = row % 2 ? '#dddddd' : '#ffffff'; context.fillRect(0, y, 480, 30);
+ context.fillStyle = '#262626'; context.fillText(`${String(row + 1).padStart(2, '0')} Cindy capture — ${row * 7919} ${row * 541} ${row * 1237}`, 12, y + 21);
+ }
+ return imageDataToBitmap(context.getImageData(0, 0, 480, 240));
+}
+
+// The native handoff is covered in windows.test.ts and the real Desktop run.
+// This adapter mounts the actual independent editor after the capture exports its image.
+function ScrollFixture({ bridge, locale }: { bridge: RegionScreenshotOverlayBridge; locale: string }) {
+ const [image, setImage] = useState<RegionScreenshotBitmap | null>(null);
+ const [clip, setClip] = useState<RecordingPreviewDocument | null>(null);
+ const captureBridge = useMemo(() => ({ ...bridge,
+ previewRecording: async (_token: string, bytes: Uint8Array, format: 'webm' | 'gif') => { setClip({ token: 'clip', locale, bytes: new Uint8Array(bytes), format }); return true; },
+ restoreEditor: async (_token: string, next: RegionScreenshotBitmap) => { qa.restored = true; setImage(next); return true; },
+ }), [bridge, locale]);
+ const editorBridge = useMemo(() => {
+ let begin: Parameters<RegionScreenshotOverlayBridge['onBegin']>[0] | undefined;
+ return { ...bridge,
+ onBegin: (callback: typeof begin) => { begin = callback; return () => { begin = undefined; }; },
+ shellReady: () => { if (image) queueMicrotask(() => begin?.({ token: 'editor', locale, viewport: image, frame: image, scaleFactor: 1, windows: [], cursor: null, lastRegion: { x: 100, y: 100, width: 480, height: 240 }, safeArea: { x: 0, y: 0, width: image.width, height: image.height } })); },
+ };
+ }, [bridge, image, locale]);
+ if (clip) return <RecordingPreview document={clip} bridge={{
+ ready() {}, failed() {}, onBegin: () => () => {}, onEnd: () => () => {}, painted() {}, close() { qa.closed = true; }, minimize() {},
+ copy: async () => { if (++qa.copyAttempts === 1) return false; qa.copied = true; return true; },
+ save: async () => { if (++qa.saveAttempts === 1) return false; qa.saved = clip.bytes; qa.format = clip.format; return true; },
+ }} />;
+ return image ? <RegionScreenshotOverlay key="editor" imageEditor bridge={editorBridge} /> : <RegionScreenshotOverlay key="capture" bridge={captureBridge} />;
+}
+
+mountPage({
+ render: (ctx) => {
+ const mode = (['default', 'idle', 'inactive', 'drag', 'preview-motion'].includes(ctx.case) ? 'scroll' : ctx.case) as RegionCaptureMode;
+ qa.idle = ctx.case === 'idle';
+ qa.manualScroll = ctx.case === 'preview-motion' ? 300 : null;
+ let begin: Parameters<RegionScreenshotOverlayBridge['onBegin']>[0] | undefined;
+ let selected = { x: 100, y: 100, width: 480, height: 240 };
+ const bridge: RegionScreenshotOverlayBridge = {
+ autoScroll: async (_token, enabled) => { qa.automatic = enabled; return true; },
+ shellReady() { queueMicrotask(() => begin?.({ token: 'fixture', locale: ctx.locale, viewport: { width: innerWidth, height: innerHeight }, scaleFactor: 1, frame: frame(), windows: [], lastRegion: null, cursor: ctx.case === 'inactive' ? null : { x: 0, y: 0 }, safeArea: { x: 0, y: 0, width: innerWidth, height: innerHeight } })); },
+ onBegin: (callback) => { begin = callback; return () => { begin = undefined; }; }, onEnd: () => () => {}, onClear: () => () => {},
+ painted() {}, focused() {}, selectionStarted() {}, copyText() {}, cancel() {}, abandon() {},
+ elementsAt: async () => [], startLive: async (_token, captureMode, selection) => { selected = selection; return { mode: captureMode, selection, first: frame(qa.manualScroll ?? 0), scrollLayout: scrollCaptureLayout(selection, { width: innerWidth, height: innerHeight })!, recordingLayout: { viewport: { width: innerWidth, height: innerHeight }, controls: recordingControlsBounds(selection, { width: innerWidth, height: innerHeight }, false)! } }; },
+ recordingControls: async (_token, expanded, point) => recordingControlsBounds(selected, { width: innerWidth, height: innerHeight }, expanded, point),
+ previewRecording: async () => false,
+ restoreEditor: async () => { qa.restored = true; return true; },
+ holdCapture: async () => {},
+ liveFrame: async (_token, keys) => {
+ qa.keysRequested ||= keys;
+ if (!qa.frames) qa.firstFrameAt = performance.now();
+ qa.frames++;
+ if (!qa.idle) qa.scrollFrames++;
+ const image = frame(qa.manualScroll ?? (mode === 'scroll' ? Math.min(qa.scrollLimit, qa.scrollFrames * 30) : qa.frames % 10));
+ // A source window repaints after the frozen selection, before any scroll.
+ // Deliberately larger than a caret so this also exercises unmatched startup.
+ if (qa.idle) image.data.fill(255, 480 * 4 * 60, 480 * 4 * 140);
+ return { image, autoScrolling: qa.automatic, cursor: { x: 100 + qa.frames, y: 80 }, keys: ['Ctrl', 'C'] };
+ },
+ saveRecording: async (_token, bytes, format) => { qa.saved = bytes; qa.format = format; return true; },
+ exportImage: async (_token, payload) => {
+ qa.exportedHeight = payload.image.height;
+ for (let i = 0; i < payload.image.data.length; i += 4) if (payload.image.data[i + 2] > 180 && payload.image.data[i] < 100) qa.annotationPixels++;
+ return true;
+ },
+ };
+ return <ScrollFixture bridge={bridge} locale={ctx.locale} />;
+ },
+});
diff --git a/apps/desktop/scripts/fixtures/region-capture/ui-page.mjs b/apps/desktop/scripts/fixtures/region-capture/ui-page.mjs
new file mode 100644
index 0000000000..b09da3dabc
--- /dev/null
+++ b/apps/desktop/scripts/fixtures/region-capture/ui-page.mjs
@@ -0,0 +1,325 @@
+import assert from 'node:assert/strict';
+export default {
+ name: 'region-capture', entry: './capture-fixture.tsx', viewport: { width: 900, height: 700 },
+ real: 'RegionScreenshotOverlay, ScrollCaptureOverlay, LiveCapturePanel, ScrollCapture, CaptureRecorder, real Chromium canvas/MediaRecorder and GIF encoding',
+ notCovered: 'Native screen acquisition, global keyboard sampling, macOS permissions and native save dialogs; frame source is synthetic.',
+ cases: {
+ default: { about: 'Scroll overlapping text, finish, export the actual stitched pixels' },
+ idle: { about: 'Repainting before the first scroll keeps the gesture hint, then scrolling still exports a long image' },
+ 'preview-motion': { about: 'Prepending reveals new rows without jumping existing content; growth and scrolling share one animation' },
+ inactive: { about: 'Only the display under the pointer shows capture controls' },
+ drag: { about: 'Move the top toolbar horizontally without selecting pixels or leaving screen bounds' },
+ video: { about: 'Record, annotate, pause/resume, save and decode a WebM' },
+ gif: { about: 'Record, annotate, pause/resume, save and decode an animated GIF' },
+ },
+ async ready(page) { await page.locator('canvas').first().waitFor(); },
+ async check(page, ui) {
+ if (ui.case === 'preview-motion') await page.emulateMedia({ reducedMotion: 'no-preference' });
+ const isScroll = ['default', 'idle', 'preview-motion'].includes(ui.case);
+ const button = async (key) => page.getByRole('button', { name: await ui.t(key), exact: true });
+ let pausedAt = 0, resumedAt = 0;
+ // e2e: exercise the real pointer capture path. Dragging the handle must move
+ // only the toolbar, retain its top position, and keep both ends reachable.
+ if (ui.case === 'drag') {
+ const handle = await button('regionScreenshot.moveToolbar');
+ const bar = handle.locator('..');
+ const initial = await bar.boundingBox();
+ const move = async (x, y) => {
+ const grip = await handle.boundingBox();
+ await page.mouse.move(grip.x + grip.width / 2, grip.y + grip.height / 2);
+ await page.mouse.down(); await page.mouse.move(x, y, { steps: 10 }); await page.mouse.up();
+ };
+ const grip = await handle.boundingBox();
+ // Longer translations have less free space. Exercise an unconstrained
+ // move first; the following drags independently verify both screen edges.
+ const distance = Math.min(100, (page.viewportSize().width - initial.width) / 4);
+ assert.ok(distance > 0);
+ await move(grip.x + grip.width / 2 + distance, grip.y + 150);
+ let bounds = await bar.boundingBox();
+ assert.ok(Math.abs(bounds.x - initial.x - distance) < 1);
+ assert.equal(bounds.y, initial.y);
+ await move(899, 400);
+ bounds = await bar.boundingBox();
+ assert.ok(bounds.x + bounds.width <= 893);
+ await move(1, 400);
+ const leftBounds = await bar.boundingBox();
+ // CSS centering can round a fractional width by half a layout subpixel.
+ assert.ok(Math.abs(leftBounds.x - 8) < 0.02, JSON.stringify(leftBounds));
+ await (await button('regionScreenshot.live.scroll')).click();
+ assert.equal(await (await button('regionScreenshot.live.startScroll')).count(), 0, 'dragging the toolbar does not create a capture selection');
+ assert.equal(await page.evaluate(() => window.captureQa.frames), 0);
+ await ui.capture('dragged');
+ return;
+ }
+ // e2e regression: previously every monitor showed its own mode bar. A begin
+ // payload with no local cursor models the second screen; entry/exit must
+ // transfer visible controls without relying on emulated document focus.
+ if (ui.case === 'inactive') {
+ const mode = await button('regionScreenshot.live.scroll');
+ assert.equal(await mode.count(), 0);
+ await page.mouse.move(20, 100);
+ await mode.waitFor({ state: 'visible' });
+ await ui.capture('active');
+ await page.mouse.move(-10, -10);
+ await mode.waitFor({ state: 'hidden' });
+ return;
+ }
+ if (!isScroll) {
+ await (await button('regionScreenshot.live.video')).click();
+ assert.equal(await page.getByRole('button', { name: 'GIF', exact: true }).count(), 0, 'GIF is a format after selection, not a top-level mode');
+ await page.mouse.move(100, 80); await page.mouse.down();
+ await page.mouse.move(580, 320, { steps: 8 }); await page.mouse.up();
+ if (ui.case === 'gif') await page.getByRole('button', { name: 'GIF', exact: true }).click();
+ assert.equal(await page.getByRole('checkbox').count(), 0, 'recording needs no pointer or keystroke settings');
+ assert.equal(await page.evaluate(() => window.captureQa.frames), 0);
+ await ui.capture('prepare');
+ await (await button('regionScreenshot.live.start')).click();
+ await ui.capture('countdown');
+ assert.equal(await page.evaluate(() => window.captureQa.frames), 0, 'countdown is not recorded');
+ await page.waitForFunction(() => window.captureQa.frames >= 3);
+ assert.equal(await page.evaluate(() => window.captureQa.keysRequested), false, 'recording does not request keyboard input');
+ assert.equal(await page.locator('canvas').count(), 0, 'recording has no permanent thumbnail');
+ await ui.capture('compact-controls');
+ // User regression: dragging the format/time area did nothing. Exercise real
+ // pointer capture, including release and continued recording after the move.
+ const bar = page.getByRole('region', { name: await ui.t('regionScreenshot.live.video'), exact: true });
+ const initial = await bar.boundingBox();
+ const label = await bar.getByText(ui.case === 'gif' ? 'GIF' : 'WebM', { exact: true }).boundingBox();
+ await page.mouse.move(label.x + label.width / 2, label.y + label.height / 2);
+ await page.mouse.down();
+ await page.mouse.move(label.x + label.width / 2 + 90, label.y + label.height / 2 + 40, { steps: 6 });
+ await page.mouse.up();
+ const moved = await bar.boundingBox();
+ assert.ok(Math.abs(moved.x - initial.x - 90) < 1 && Math.abs(moved.y - initial.y - 40) < 1, 'format/time area moves the recording toolbar');
+ await page.mouse.move(20, 600);
+ assert.deepEqual(await bar.boundingBox(), moved, 'toolbar stays put after release');
+ await ui.capture('dragged-recording-controls');
+ }
+ else {
+ const modeButton = await button('regionScreenshot.live.scroll');
+ assert.ok((await modeButton.boundingBox()).y < 60, 'capture modes are at the screen top before selection');
+ await modeButton.click();
+ assert.equal(await page.locator('button[aria-pressed="true"]').count(), 1);
+ await page.mouse.move(100, 100); await page.mouse.down();
+ await page.mouse.move(580, 340, { steps: 8 }); await page.mouse.up();
+ assert.equal(await page.evaluate(() => window.captureQa.frames), 0, 'choosing a mode and a region does not start capture');
+ await ui.capture('ready');
+ await (await button('regionScreenshot.live.startScroll')).click();
+ assert.equal(await (await button('regionScreenshot.live.pause')).count(), 0, 'scrolling has no separate capture toolbar');
+ assert.equal(await page.getByRole('complementary').count(), 1, 'the selection has an inline stitched preview');
+ const previewStyle = await page.getByRole('complementary').evaluate(el => {
+ const box = el.getBoundingClientRect(), css = getComputedStyle(el);
+ return { bottom: box.bottom, x: box.x, border: css.borderWidth, background: css.backgroundColor };
+ });
+ assert.equal(previewStyle.bottom, 340, 'preview starts at the selection bottom');
+ assert.ok(previewStyle.x > 580, 'preview prefers the right side');
+ assert.equal(previewStyle.border, '0px', 'image has no surrounding frame');
+ assert.equal(previewStyle.background, 'rgba(0, 0, 0, 0)', 'image has no opaque backing');
+ }
+ if (ui.case === 'preview-motion') {
+ // e2e regression: at each real paint, follow a row already in the image.
+ // A prepended strip must grow upward without moving that old row down first.
+ // The existing long-preview test only checks final geometry, missing this jump.
+ const motion = await page.evaluate(async () => {
+ const panel = document.querySelector('aside');
+ const view = panel.querySelector('[tabindex="0"]');
+ const strip = view.firstElementChild;
+ const initial = panel.getBoundingClientRect();
+ const extent = strip.getBoundingClientRect().height;
+ const rows = [];
+ window.captureQa.manualScroll = 180;
+ await new Promise(resolve => {
+ const start = performance.now();
+ const tick = () => {
+ const box = panel.getBoundingClientRect();
+ rows.push({ height: box.height, bottom: box.bottom, anchor: box.top + strip.getBoundingClientRect().height - extent - view.scrollTop });
+ if (performance.now() - start < 650) requestAnimationFrame(tick); else resolve();
+ };
+ requestAnimationFrame(tick);
+ });
+ return { initial: { top: initial.top, height: initial.height }, rows };
+ });
+ assert.ok(motion.rows.at(-1).height > motion.initial.height + 10, 'new rows were stitched');
+ assert.ok(motion.rows.some(row => row.height > motion.initial.height + 1 && row.height < motion.rows.at(-1).height - 1), 'growth has intermediate frames');
+ assert.ok(motion.rows.every(row => Math.abs(row.bottom - 340) < 1), 'bottom anchor is stable');
+ const jump = Math.max(...motion.rows.map(row => Math.abs(row.anchor - motion.initial.top)));
+ assert.ok(jump < 2, `existing image rows jumped by ${jump.toFixed(2)}px during prepend`);
+ await ui.capture('smooth-prepend');
+ const frames = await page.evaluate(() => { window.captureQa.manualScroll = 300; return window.captureQa.frames; });
+ await page.waitForFunction(n => window.captureQa.frames >= n + 2, frames);
+ await page.evaluate(() => { window.captureQa.manualScroll = 420; });
+ await page.waitForFunction(() => {
+ const p = document.querySelector('aside');
+ return p.getBoundingClientRect().height >= p.getBoundingClientRect().width - 1;
+ });
+ const scrolling = await page.evaluate(async () => {
+ const panel = document.querySelector('aside');
+ const view = panel.querySelector('[tabindex="0"]');
+ const samples = [];
+ window.captureQa.manualScroll = 540;
+ await new Promise(resolve => {
+ const start = performance.now();
+ const tick = () => {
+ samples.push({ height: panel.getBoundingClientRect().height, scroll: view.scrollTop });
+ if (performance.now() - start < 650) requestAnimationFrame(tick); else resolve();
+ };
+ requestAnimationFrame(tick);
+ });
+ return { samples, end: view.scrollHeight - view.clientHeight };
+ });
+ assert.ok(scrolling.end > 0 && Math.abs(scrolling.samples.at(-1).scroll - scrolling.end) < 2, 'append follows the new bottom after reaching the panel limit');
+ assert.ok(scrolling.samples.some(row => row.scroll > 1 && row.scroll < scrolling.end - 1), 'following new rows has intermediate frames');
+ await ui.capture('smooth-append');
+ await page.emulateMedia({ reducedMotion: 'reduce' });
+ await page.evaluate(() => { window.captureQa.manualScroll = 660; });
+ await page.waitForFunction(() => {
+ const view = document.querySelector('aside [tabindex="0"]');
+ return view.firstElementChild.getBoundingClientRect().height >= 450;
+ });
+ assert.ok(await page.locator('aside [tabindex="0"]').evaluate(el => Math.abs(el.scrollHeight - el.clientHeight - el.scrollTop) < 2), 'reduced motion reaches the new bottom without animation');
+ return;
+ }
+ if (ui.case === 'idle') {
+ // e2e regression: the old panel displayed a lost-overlap warning after
+ // 1.5 seconds even though the source had only repainted without scrolling.
+ await page.waitForFunction(() => window.captureQa.frames >= 10);
+ assert.equal(await page.getByRole('status').innerText(), await ui.t('regionScreenshot.live.scrollHint'));
+ await ui.capture('waiting-for-scroll');
+ await page.evaluate(() => { window.captureQa.idle = false; });
+ await page.waitForFunction(() => window.captureQa.scrollFrames >= 3);
+ }
+ await page.waitForFunction(() => window.captureQa.frames >= 3);
+ if (isScroll) {
+ await (await button('regionScreenshot.live.autoScroll')).click();
+ await page.waitForFunction(() => window.captureQa.automatic);
+ await (await button('regionScreenshot.live.stopScroll')).click();
+ await page.waitForFunction(() => !window.captureQa.automatic);
+ await ui.capture('scrolling');
+ if (ui.case === 'default') {
+ // Regression: a growing screenshot previously shrank to fit the panel.
+ // Real canvas output must retain its width, scroll to new content and allow review.
+ const thumbnail = page.getByRole('complementary').locator('canvas');
+ const width = await thumbnail.evaluate(el => el.width);
+ await page.evaluate(() => { window.captureQa.scrollLimit = 600; });
+ await page.waitForFunction(() => window.captureQa.scrollFrames >= 21);
+ assert.equal(await thumbnail.evaluate(el => el.width), width);
+ assert.equal((await page.getByRole('complementary').boundingBox()).y + (await page.getByRole('complementary').boundingBox()).height, 340, 'preview keeps its bottom anchor as it grows');
+ const viewport = page.getByRole('complementary').locator('[tabindex="0"]');
+ assert.ok(await viewport.evaluate(el => el.scrollHeight > el.clientHeight && el.scrollTop > 0));
+ await ui.capture('long-preview');
+ await viewport.hover(); await page.mouse.wheel(0, -1000);
+ await page.waitForFunction(() => document.querySelector('aside [tabindex="0"]').scrollTop === 0);
+ }
+ }
+ if (!isScroll) {
+ pausedAt = await page.evaluate(() => performance.now());
+ await (await button('regionScreenshot.live.pause')).click();
+ const frames = await page.evaluate(() => window.captureQa.frames);
+ // e2e: cross a real capture tick to prove that the user-visible pause stops sampling.
+ await page.waitForTimeout(ui.case === 'video' ? 1600 : 400);
+ assert.equal(await page.evaluate(() => window.captureQa.frames), frames);
+ await ui.capture('paused');
+ if (!isScroll) {
+ await (await button('regionScreenshot.live.annotate')).click();
+ await (await button('regionScreenshot.tools.arrow')).click();
+ const box = await page.locator('canvas').boundingBox();
+ await page.mouse.move(box.x + box.width * 0.2, box.y + box.height * 0.4);
+ await page.mouse.down();
+ await page.mouse.move(box.x + box.width * 0.7, box.y + box.height * 0.6, { steps: 8 });
+ await page.mouse.up();
+ }
+ await (await button('regionScreenshot.live.resume')).click();
+ resumedAt = await page.evaluate(() => performance.now());
+ await page.waitForFunction((previous) => window.captureQa.frames >= previous + 3, frames);
+ await ui.capture('capturing');
+ }
+ const sampledDuration = await page.evaluate(() => performance.now() - window.captureQa.firstFrameAt) - (resumedAt - pausedAt);
+ await (await button(isScroll ? 'regionScreenshot.live.edit' : 'regionScreenshot.live.finish')).click();
+ if (isScroll) {
+ await page.setViewportSize({ width: 900, height: 700 });
+ await page.waitForFunction(() => window.captureQa.restored);
+ const arrow = await ui.t('regionScreenshot.tools.arrow');
+ await page.getByRole('button', { name: `${arrow} (A)`, exact: true }).click();
+ const box = await page.locator('canvas').first().boundingBox();
+ await page.mouse.move(box.x + box.width * 0.2, box.y + box.height * 0.2); await page.mouse.down();
+ await page.mouse.move(box.x + box.width * 0.7, box.y + box.height * 0.4, { steps: 8 }); await page.mouse.up();
+ await ui.capture('independent-editor');
+ const dimensions = await page.locator('canvas').first().evaluate(el => [el.width, el.height]);
+ await (await button('remoteDesktop.fit')).click();
+ await (await button('remoteDesktop.actualSize')).click();
+ // The idle case produces a short image. Give it a smaller editing window
+ // so a wheel gesture has real overflow to scroll, just as with a long capture.
+ if (ui.case === 'idle') await page.setViewportSize({ width: 900, height: 400 });
+ const review = page.locator('[tabindex="0"]');
+ assert.ok(await review.evaluate(el => el.scrollHeight > el.clientHeight), 'the editor has overflow to review');
+ await review.evaluate(el => { el.scrollTop = 0; });
+ await review.hover(); await page.mouse.wheel(0, 300);
+ await page.waitForFunction(() => document.querySelector('[tabindex="0"]').scrollTop > 0);
+ assert.deepEqual(await page.locator('canvas').first().evaluate(el => [el.width, el.height]), dimensions, 'zoom and scrolling do not resample the source');
+ // The shortcut hint follows the host platform: "(Ctrl+S)" on Windows, "(⌘S)" on macOS.
+ const save = (await ui.t('regionScreenshot.save')).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+ await page.getByRole('button', { name: new RegExp(`^${save} \\((Ctrl\\+|⌘)S\\)$`) }).click();
+ await page.waitForFunction(() => window.captureQa.exportedHeight > 240);
+ assert.ok(await page.evaluate(() => window.captureQa.annotationPixels > 0), 'independent editor annotations are included in the full-resolution export');
+ } else {
+ await (await button('regionScreenshot.save')).waitFor();
+ await (await button('regionScreenshot.save')).click();
+ assert.equal(await page.evaluate(() => window.captureQa.saved), null, 'cancelling the save dialog retains playback');
+ await (await button('regionScreenshot.copy')).click();
+ await page.getByRole('alert').filter({ hasText: await ui.t('regionScreenshot.live.copyFailed') }).waitFor();
+ assert.equal(await page.evaluate(() => window.captureQa.closed), false, 'failed copy keeps playback available');
+ await (await button('regionScreenshot.copy')).click();
+ await page.waitForFunction(() => window.captureQa.copied);
+ await page.getByRole('status').filter({ hasText: await ui.t('regionScreenshot.live.copied') }).waitFor();
+ if (ui.case === 'video') {
+ await page.waitForFunction(() => document.querySelector('video')?.readyState >= 2);
+ assert.ok(await page.locator('video').evaluate(video => Number.isFinite(video.duration) && video.duration > 0), 'finished WebM has a usable timeline');
+ const initial = await page.locator('video').evaluate(video => ({ time: video.currentTime, duration: video.duration, paused: video.paused }));
+ assert.equal(initial.time, 0, 'new playback starts at zero');
+ assert.equal(initial.paused, true, 'preview does not advance before Play');
+ assert.ok(Math.abs(initial.duration * 1000 - sampledDuration) < 750, 'duration excludes countdown and paused time');
+ await page.locator('video').evaluate(video => video.play());
+ await page.waitForFunction(() => document.querySelector('video').currentTime > 0);
+ await page.locator('video').evaluate(video => { video.pause(); video.currentTime = video.duration / 2; });
+ await page.waitForFunction(() => { const video = document.querySelector('video'); return !video.seeking && Math.abs(video.currentTime - video.duration / 2) < 0.05; });
+ await page.locator('video').evaluate(video => { video.currentTime = 0; });
+ await page.waitForFunction(() => { const video = document.querySelector('video'); return !video.seeking && video.currentTime === 0; });
+ // User feedback: fullscreen did nothing, and Esc must not discard the clip.
+ // Browser coverage checks exit behavior; native window entry is verified in Electron.
+ await page.locator('video').evaluate(video => video.requestFullscreen());
+ await page.waitForFunction(() => document.fullscreenElement === document.querySelector('video'));
+ await ui.capture('fullscreen-playback');
+ await page.keyboard.press('Escape');
+ await page.waitForFunction(() => !document.fullscreenElement);
+ assert.equal(await page.evaluate(() => window.captureQa.closed), false, 'Esc exits fullscreen without closing playback');
+ } else {
+ await page.waitForFunction(() => document.querySelector('img')?.naturalWidth > 0);
+ await (await button('regionScreenshot.live.replay')).click();
+ }
+ await ui.capture('independent-playback');
+ await (await button('regionScreenshot.save')).click();
+ await page.waitForFunction(() => window.captureQa.saved?.length > 0);
+ const clip = await page.evaluate(() => ({ saved: Array.from(window.captureQa.saved), format: window.captureQa.format }));
+ // Decode the exported bytes independently from the preview window.
+ const playback = await page.context().newPage();
+ let decoded;
+ try { decoded = await playback.evaluate(async ({ saved, format }) => {
+ saved = new Uint8Array(saved);
+ const url = URL.createObjectURL(new Blob([saved], { type: format === 'gif' ? 'image/gif' : 'video/webm' }));
+ try {
+ if (format === 'gif') {
+ const image = new Image(); image.src = url; await image.decode();
+ return { width: image.naturalWidth, height: image.naturalHeight };
+ }
+ const video = document.createElement('video'); video.muted = true; video.src = url;
+ await new Promise((resolve, reject) => { video.onloadeddata = resolve; video.onerror = reject; });
+ if (!Number.isFinite(video.duration) || video.duration <= 0 || video.currentTime !== 0) throw new Error('Saved video has an invalid timeline');
+ const size = { width: video.videoWidth, height: video.videoHeight };
+ video.removeAttribute('src'); video.load();
+ return size;
+ } finally { URL.revokeObjectURL(url); }
+ }, clip); } finally { await playback.close(); }
+ assert.deepEqual(decoded, { width: 480, height: 240 });
+ }
+ },
+};
diff --git a/apps/desktop/src/main/__tests__/mainWindowBackgroundThrottling.test.ts b/apps/desktop/src/main/__tests__/mainWindowBackgroundThrottling.test.ts
index 297df9d967..aaa946c395 100644
--- a/apps/desktop/src/main/__tests__/mainWindowBackgroundThrottling.test.ts
+++ b/apps/desktop/src/main/__tests__/mainWindowBackgroundThrottling.test.ts
@@ -181,6 +181,14 @@ describe('窗口可见性广播(装饰动画闸门的兜底信号)', () => {
* 豁免必须显式登记并写明理由——目的是逼一次判断,而不是让人默默跳过。
*/
const BROADCAST_EXEMPT = new Map<string, string>([
+ [
+ 'region-screenshot/pageWindow.ts',
+ // index.tsx dispatches these windows to region-screenshot(-pin)-entry,
+ // not main-entry: neither installs hiddenAnimationGate or runs decorative
+ // animations. Capture timers belong to the explicit capture session;
+ // ending it unmounts the panel, while pin windows are destroyed on close.
+ '截图与贴图使用独立轻量入口,无常驻装饰动画;隐藏预热需要及时绘制首帧',
+ ],
[
'remote-desktop/captureWindow.ts',
'独立捕获页不加载聊天 Renderer 或装饰动画;只在媒体连接期间存在,停止时销毁',
diff --git a/apps/desktop/src/main/app-shortcuts/AppShortcutStore.ts b/apps/desktop/src/main/app-shortcuts/AppShortcutStore.ts
index 6113c2bd58..de50862287 100644
--- a/apps/desktop/src/main/app-shortcuts/AppShortcutStore.ts
+++ b/apps/desktop/src/main/app-shortcuts/AppShortcutStore.ts
@@ -10,6 +10,7 @@ import {
isAppShortcutAvailableOnPlatform,
isAppShortcutComboBindable,
isAppShortcutId,
+ isGlobalAppShortcutComboUsable,
normalizeAppShortcutCombo,
normalizeAppShortcutOverrides,
type AppShortcutCombo,
@@ -34,6 +35,7 @@ export type AppShortcutOverrideRejection =
| 'not-bindable'
| 'system-reserved'
| 'menu-inexpressible'
+ | 'global-unusable'
| 'conflict';
export interface AppShortcutStoreOptions {
@@ -111,6 +113,9 @@ export class AppShortcutStore {
) {
return 'menu-inexpressible';
}
+ if (def.scope === 'global' && !isGlobalAppShortcutComboUsable(normalized, this.options.platform)) {
+ return 'global-unusable';
+ }
const current = this.load();
// 跨 id 冲突兜底 (renderer 已前置校验, 这里防多窗口并发 / 直调 IPC):
// 与重叠 scope 域内其它 id 的生效组合撞键则拒绝。
diff --git a/apps/desktop/src/main/app-shortcuts/__tests__/AppShortcutStore.test.ts b/apps/desktop/src/main/app-shortcuts/__tests__/AppShortcutStore.test.ts
index 35634952ed..9f0a4174b4 100644
--- a/apps/desktop/src/main/app-shortcuts/__tests__/AppShortcutStore.test.ts
+++ b/apps/desktop/src/main/app-shortcuts/__tests__/AppShortcutStore.test.ts
@@ -114,6 +114,27 @@ describe('AppShortcutStore', () => {
expect(winStore.setOverride('new-maker', combo('IntlYen', { ctrl: true }))).toBeNull();
});
+ it('guards the system-wide screenshot shortcut', () => {
+ const store = makeStore('win32');
+ // 全局键在所有应用里截走按键: 占用 Ctrl+C 会让别的应用无法复制
+ expect(store.setOverride('region-screenshot', combo('KeyC', { ctrl: true }))).toBe(
+ 'global-unusable',
+ );
+ // globalShortcut 只认 accelerator: NumpadAdd 表达不了, 绑定后永远不会触发
+ expect(
+ store.setOverride('region-screenshot', combo('NumpadAdd', { ctrl: true, alt: true })),
+ ).toBe('global-unusable');
+ expect(store.setOverride('region-screenshot', combo('KeyA', { ctrl: true, alt: true }))).toBeNull();
+ // Cindy 在前台时全局键同样先截走按键, 浏览器域的应用内快捷键也不能与它同键
+ expect(
+ store.setOverride('browser-focus-url', combo('KeyA', { ctrl: true, alt: true })),
+ ).toBe('conflict');
+ // 暂不支持 Linux
+ expect(
+ makeStore('linux').setOverride('region-screenshot', combo('KeyA', { ctrl: true, alt: true })),
+ ).toBe('platform-unavailable');
+ });
+
it('setOverride(null) deletes the binding: effective combos become empty', () => {
const store = makeStore('darwin');
expect(store.setOverride('find-in-page', null)).toBeNull();
diff --git a/apps/desktop/src/main/app-shortcuts/index.ts b/apps/desktop/src/main/app-shortcuts/index.ts
index ae87fff908..39b04377f5 100644
--- a/apps/desktop/src/main/app-shortcuts/index.ts
+++ b/apps/desktop/src/main/app-shortcuts/index.ts
@@ -2,7 +2,7 @@ import { app, BrowserWindow, ipcMain } from 'electron';
import path from 'node:path';
import { throwIpcError } from '../utils/ipcValidate.js';
-import type { AppShortcutOverrides } from '../../shared/appShortcuts.js';
+import type { AppShortcutId, AppShortcutOverrides } from '../../shared/appShortcuts.js';
import {
AppShortcutStore,
APP_SHORTCUTS_FILE_NAME,
@@ -19,10 +19,26 @@ import {
* - set-override / clear-override / reset-all (invoke): 写路径, 校验失败
* throwIpcError('INVALID_PARAMS')。
* - changed (main → renderer 广播): overrides 全量快照, renderer 热更新。
+ *
+ * get / changed 同时携带 globalFailures: global scope 条目中当前生效组合
+ * 向系统注册失败 (多为被其它应用占用) 的 id, 设置页据此提示。它是运行态,
+ * 不落盘; 由注册方 (如 region-screenshot) 通过
+ * setGlobalShortcutRegistrationFailures 上报。
*/
let storeSingleton: AppShortcutStore | null = null;
let ipcRegistered = false;
+let globalFailures: AppShortcutId[] = [];
+
+/** 注册方上报当前注册失败的 global 条目; 变化时连同 overrides 一起广播。 */
+export function setGlobalShortcutRegistrationFailures(ids: readonly AppShortcutId[]): void {
+ const next = [...new Set(ids)].sort();
+ if (next.length === globalFailures.length && next.every((id, i) => id === globalFailures[i])) {
+ return;
+ }
+ globalFailures = next;
+ broadcastAppShortcutsChanged(getAppShortcutStore().getOverrides());
+}
// ── 录制态 gate ──────────────────────────────────────────────────────────
// 设置页录制快捷键期间, renderer 的 useAppShortcut 靠 body dataset 让路,
@@ -69,6 +85,7 @@ export function registerAppShortcutIpc(): void {
event.returnValue = {
overrides: store.getOverrides(),
platform: process.platform,
+ globalFailures: [...globalFailures],
};
});
@@ -134,6 +151,8 @@ function rejectionMessage(rejection: AppShortcutOverrideRejection, id: unknown):
return 'shortcut combo is reserved by the operating system';
case 'menu-inexpressible':
return 'shortcut combo cannot be expressed as a menu accelerator on macOS';
+ case 'global-unusable':
+ return 'shortcut combo cannot be used as a system-wide shortcut';
case 'conflict':
return 'shortcut combo conflicts with another shortcut in an overlapping scope';
}
@@ -142,6 +161,9 @@ function rejectionMessage(rejection: AppShortcutOverrideRejection, id: unknown):
function broadcastAppShortcutsChanged(overrides: AppShortcutOverrides): void {
BrowserWindow.getAllWindows().forEach((window) => {
if (window.isDestroyed()) return;
- window.webContents.send('app-shortcuts:changed', { overrides });
+ window.webContents.send('app-shortcuts:changed', {
+ overrides,
+ globalFailures: [...globalFailures],
+ });
});
}
diff --git a/apps/desktop/src/main/bootstrap-electron.ts b/apps/desktop/src/main/bootstrap-electron.ts
index c8963493f4..cfc0250f07 100644
--- a/apps/desktop/src/main/bootstrap-electron.ts
+++ b/apps/desktop/src/main/bootstrap-electron.ts
@@ -594,6 +594,7 @@ import { readFileBytesForPreview } from './fileReadBytes.js';
import { copyPngToClipboard } from './pngClipboard.js';
import { COPY_PNG_TO_CLIPBOARD_CHANNEL } from '../shared/pngClipboard.js';
import { copyTextToClipboard } from './textClipboard.js';
+import { copyFileToClipboardWindows, copyFileToClipboardMacOS } from './fileClipboard.js';
import { COPY_TEXT_TO_CLIPBOARD_CHANNEL } from '../shared/textClipboard.js';
import {
readLinuxClipboardSnapshot,
@@ -986,6 +987,7 @@ import { disposeRemoteFileBrowser } from './file-browser/remote-deps.js';
import { registerFileBrowserDeviceOp } from './file-browser/device-op.js';
import { registerSearchIpc } from './file-browser/search/index.js';
import { registerVoiceInputIpc } from './voice-input/index.js';
+import { initRegionScreenshot, stopRegionScreenshot } from './region-screenshot/index.js';
import { installWindowHiddenBroadcast } from './windowHiddenBroadcast.js';
import { getRenderWatchdogContext } from './renderWatchdogContext.js';
import {
@@ -4573,6 +4575,10 @@ const registerIpcHandlers = () => {
});
app.once('will-quit', stopMenubarService);
+ // 全局框选截图快捷键 (键盘快捷键设置里可改),支持复制、保存、贴图与新任务。
+ initRegionScreenshot();
+ app.once('will-quit', stopRegionScreenshot);
+
// 「在新窗口打开」会话多开 —— 新建一个完整窗口定位到该 session, 初始 bounds 取主窗。
ipcMain.handle(
MAKER_IPC_INVOKE.OPEN_SESSION_IN_NEW_WINDOW,
@@ -8182,57 +8188,6 @@ const registerIpcHandlers = () => {
// that paste-into-folder accepts. spawn (no shell) is used to keep the
// path argument out of any shell-quote interpretation.
- /** Windows: PowerShell `Set-Clipboard -LiteralPath` writes CF_HDROP. */
- function copyFileToClipboardWindows(absPath: string): Promise<void> {
- return new Promise((resolve, reject) => {
- // Single-quoted PS string is literal except for `'` itself; double it
- // to escape. Path can contain spaces, `$`, backticks, etc. — all safe
- // inside single quotes.
- const escaped = absPath.replace(/'/g, "''");
- const psCommand = `Set-Clipboard -LiteralPath '${escaped}'`;
- const proc = spawn('powershell', ['-NoProfile', '-NonInteractive', '-Command', psCommand], {
- windowsHide: true,
- });
- let stderr = '';
- proc.stderr.on('data', (d) => {
- stderr += d.toString();
- });
- proc.on('error', reject);
- proc.on('exit', (code) => {
- if (code === 0) resolve();
- else reject(new Error(stderr.trim() || `Set-Clipboard exited ${code}`));
- });
- });
- }
-
- /**
- * macOS: AppleScript `set the clipboard to (POSIX file …)` writes the
- * NSPasteboardTypeFileURL pasteboard entry. The path is passed as an
- * AppleScript argv to avoid in-script escaping.
- */
- function copyFileToClipboardMacOS(absPath: string): Promise<void> {
- return new Promise((resolve, reject) => {
- const proc = spawn('osascript', [
- '-e',
- 'on run argv',
- '-e',
- 'set the clipboard to (POSIX file (item 1 of argv))',
- '-e',
- 'end run',
- absPath,
- ]);
- let stderr = '';
- proc.stderr.on('data', (d) => {
- stderr += d.toString();
- });
- proc.on('error', reject);
- proc.on('exit', (code) => {
- if (code === 0) resolve();
- else reject(new Error(stderr.trim() || `osascript exited ${code}`));
- });
- });
- }
-
// Right-click → "open file folder". Accepts xdt-image:// / xdt-video:// URLs
// (resolved via the matching cache store) or an absolute file path. On
// success, reveals the file in the OS file manager (Explorer / Finder).
diff --git a/apps/desktop/src/main/device-link/__tests__/providerShareGuestPrefs.test.ts b/apps/desktop/src/main/device-link/__tests__/providerShareGuestPrefs.test.ts
index d52cb52bf4..f82b5f33bb 100644
--- a/apps/desktop/src/main/device-link/__tests__/providerShareGuestPrefs.test.ts
+++ b/apps/desktop/src/main/device-link/__tests__/providerShareGuestPrefs.test.ts
@@ -88,15 +88,21 @@ describe('provider share guest prefs', () => {
it('publishes trust only after the atomic write succeeds', async () => {
const rename = fsp.rename;
+ let reachedRename!: () => void;
+ const renaming = new Promise<void>((resolve) => { reachedRename = resolve; });
let finishWrite!: () => void;
const pendingWrite = new Promise<void>((resolve) => { finishWrite = resolve; });
const renameSpy = vi.spyOn(fsp, 'rename').mockImplementationOnce(async (source, target) => {
+ reachedRename();
await pendingWrite;
await rename(source, target);
});
const saving = setProviderShareCredentialConsent('share-1', 'global', true);
try {
- await vi.waitFor(() => expect(renameSpy).toHaveBeenCalled());
+ // 等真实写入到达提交点;锁与磁盘 I/O 不保证在 waitFor 默认的 1 秒内完成。
+ // 同时观察保存结果,避免 rename 前失败时只能等待测试超时。
+ await Promise.race([renaming, saving]);
+ expect(renameSpy).toHaveBeenCalled();
expect(isProviderShareCredentialConsentSkipped('share-1')).toBe(false);
} finally {
finishWrite();
diff --git a/apps/desktop/src/main/fileClipboard.ts b/apps/desktop/src/main/fileClipboard.ts
new file mode 100644
index 0000000000..abda379cfc
--- /dev/null
+++ b/apps/desktop/src/main/fileClipboard.ts
@@ -0,0 +1,23 @@
+import { execFile } from 'node:child_process';
+
+/** Native file-list clipboard formats allow paste into both chat apps and folders. */
+function run(file: string, args: string[]): Promise<void> {
+ return new Promise((resolve, reject) => {
+ execFile(file, args, { windowsHide: true, timeout: 10_000, maxBuffer: 64 * 1024 }, (error) => {
+ if (error) reject(error);
+ else resolve();
+ });
+ });
+}
+
+export function copyFileToClipboardWindows(absPath: string): Promise<void> {
+ // A single-quoted PowerShell literal only interprets doubled apostrophes.
+ return run('powershell', ['-NoProfile', '-NonInteractive', '-Command',
+ `$ErrorActionPreference = 'Stop'; Set-Clipboard -LiteralPath '${absPath.replace(/'/g, "''")}'`]);
+}
+
+export function copyFileToClipboardMacOS(absPath: string): Promise<void> {
+ // Keep the path in argv, never in AppleScript source.
+ return run('osascript', ['-e', 'on run argv', '-e',
+ 'set the clipboard to (POSIX file (item 1 of argv))', '-e', 'end run', absPath]);
+}
diff --git a/apps/desktop/src/main/maker-host/__tests__/model-context-limit-store.test.ts b/apps/desktop/src/main/maker-host/__tests__/model-context-limit-store.test.ts
index cee623ed7f..7b0b6b1cfe 100644
--- a/apps/desktop/src/main/maker-host/__tests__/model-context-limit-store.test.ts
+++ b/apps/desktop/src/main/maker-host/__tests__/model-context-limit-store.test.ts
@@ -2,7 +2,7 @@ import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
-import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { BUNDLED_CATALOG } from '@cindy/model-providers';
const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cindy-model-context-limit-'));
@@ -89,7 +89,15 @@ describe('model context limit store', () => {
// PR #7460 deletion P1, unit: existing write/reset tests did not cover removing
// every model of one connection, including off-catalog models and rollback.
+ // Windows CI #7300: successive atomic writes can share an mtime. Keep real
+ // disk writes but fix their timestamps to expose stale deletion/rollback caches.
it('clears only the exact provider compaction policies and restores after deletion failure', async () => {
+ const rename = fs.renameSync;
+ const timestamp = new Date('2026-01-01T00:00:00Z');
+ vi.spyOn(fs, 'renameSync').mockImplementation((source, target) => {
+ rename(source, target);
+ if (target === PREFS) fs.utimesSync(target, timestamp, timestamp);
+ });
const providerId = 'custom:quote"connection';
const target = { providerId, modelId: 'gpt' };
const retired = { providerId, modelId: 'retired' };
@@ -99,20 +107,7 @@ describe('model context limit store', () => {
await save([target, retired], 65);
await save([other], 80);
writeModelContextLimit('codex', providerId, 'gpt', 272_000);
- // Windows CI: the staged write can land within the cached store's mtime
- // granularity. Pin the mtime back so the stale-cache case is deterministic.
- let pinned = 1_700_000_000;
- const withSameMtime = <T>(write: () => T): T => {
- // Cache the file under an exact whole-second mtime, write, then put that
- // same mtime back: the cached store sees no change, as on Windows.
- pinned += 10;
- fs.utimesSync(PREFS, pinned, pinned);
- readModelCompactionPct(providerId, 'gpt');
- const result = write();
- fs.utimesSync(PREFS, pinned, pinned);
- return result;
- };
- const restore = withSameMtime(() => stageProviderModelCompactionClear(providerId));
+ const restore = stageProviderModelCompactionClear(providerId);
expect(readModelCompactionPct(providerId, 'gpt')).toBeNull();
expect(readModelCompactionPct(providerId, 'retired')).toBeNull();
expect(readModelCompactionPct(other.providerId, 'gpt')).toBe(80);
@@ -120,7 +115,8 @@ describe('model context limit store', () => {
expect(stageProviderModelCompactionClear(providerId)()).toBe(true);
await save([other], 70);
expect(readModelCompactionPct(other.providerId, 'gpt')).toBe(70);
- expect(withSameMtime(restore)).toBe(true);
+ expect(readModelCompactionPct(providerId, 'gpt')).toBeNull();
+ expect(restore()).toBe(true);
expect(readModelCompactionPct(providerId, 'gpt')).toBe(65);
expect(readModelCompactionPct(providerId, 'retired')).toBe(65);
expect(readModelCompactionPct(other.providerId, 'gpt')).toBe(70);
@@ -321,6 +317,8 @@ describe('model context limit store', () => {
});
});
+afterEach(() => vi.restoreAllMocks());
+
afterAll(() => fs.rmSync(tempRoot, { recursive: true, force: true }));
describe('atomic context edits', () => {
diff --git a/apps/desktop/src/main/maker-host/model-context-limit-store.ts b/apps/desktop/src/main/maker-host/model-context-limit-store.ts
index 3c82d8be9c..24ddcbe17b 100644
--- a/apps/desktop/src/main/maker-host/model-context-limit-store.ts
+++ b/apps/desktop/src/main/maker-host/model-context-limit-store.ts
@@ -147,7 +147,6 @@ export function readModelCompactionPct(providerId: string, modelId: string): num
return readPrefs().compactionPcts?.[JSON.stringify([providerId, modelId])] ?? null;
}
-/** Participate in the existing provider deletion transaction, including rollback. */
/**
* A separate owner-pinned store wrote the shared prefs file. The module store's
* mtime guard can miss that write when both land within the filesystem's mtime
@@ -157,6 +156,7 @@ function dropCachedStore(): void {
store = createStore(() => ownerScopedUserDataPath('model-context-limit-prefs.json'));
}
+/** Participate in the existing provider deletion transaction, including rollback. */
export function stageProviderModelCompactionClear(providerId: string): () => boolean {
const filePath = ownerScopedUserDataPath('model-context-limit-prefs.json');
const ownerStore = createStore(() => filePath);
@@ -171,11 +171,12 @@ export function stageProviderModelCompactionClear(providerId: string): () => boo
dropCachedStore();
return () => {
try {
- ownerStore.invalidateIfChanged();
- const current = { ...ownerStore.read().compactionPcts };
+ // Reload the pinned owner's file even when intervening writes share its mtime.
+ const rollbackStore = createStore(() => filePath);
+ const current = { ...rollbackStore.read().compactionPcts };
// Restore only removed entries; do not overwrite a newer external edit.
for (const [key, value] of Object.entries(removed)) current[key] ??= value;
- ownerStore.writePatch({ compactionPcts: current });
+ rollbackStore.writePatch({ compactionPcts: current });
dropCachedStore();
return true;
} catch (error) {
diff --git a/apps/desktop/src/main/overlayEscape.ts b/apps/desktop/src/main/overlayEscape.ts
new file mode 100644
index 0000000000..88b51c3138
--- /dev/null
+++ b/apps/desktop/src/main/overlayEscape.ts
@@ -0,0 +1,26 @@
+import { globalShortcut } from 'electron';
+
+/** 共用一个 OS Esc 注册;截图优先于语音,释放任一使用方不会注销其他人的按键。 */
+const owners = new Map<symbol, { priority: number; cancel: () => void }>();
+
+export function acquireOverlayEscape(cancel: () => void, priority = 0): (() => void) | null {
+ if (owners.size === 0) {
+ try {
+ if (
+ !globalShortcut.register('Escape', () => {
+ const current = [...owners.values()].sort((a, b) => b.priority - a.priority)[0];
+ current?.cancel();
+ })
+ )
+ return null;
+ } catch {
+ return null;
+ }
+ }
+ const key = Symbol();
+ owners.set(key, { cancel, priority });
+ return () => {
+ if (!owners.delete(key)) return;
+ if (owners.size === 0) globalShortcut.unregister('Escape');
+ };
+}
diff --git a/apps/desktop/src/main/region-screenshot/__tests__/compose.test.ts b/apps/desktop/src/main/region-screenshot/__tests__/compose.test.ts
new file mode 100644
index 0000000000..97c391391e
--- /dev/null
+++ b/apps/desktop/src/main/region-screenshot/__tests__/compose.test.ts
@@ -0,0 +1,97 @@
+import type { NativeImage } from 'electron';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+const mocks = vi.hoisted(() => ({
+ handlers: new Map<string, (event: unknown) => unknown>(),
+ ingest: vi.fn(),
+ scope: 'owner-a:1',
+ boundary: false,
+ db: {},
+ main: { isDestroyed: () => false, webContents: { mainFrame: {} } },
+}));
+vi.mock('electron', () => ({
+ ipcMain: {
+ handle: (channel: string, fn: (event: unknown) => unknown) => mocks.handlers.set(channel, fn),
+ },
+}));
+vi.mock('../../cindy-media/chatAttachments', () => ({ ingestChatImageBuffer: mocks.ingest }));
+vi.mock('../../appSessionState', () => ({
+ activeOwnerScopeKey: () => mocks.scope,
+ isAppSessionBoundaryPending: () => mocks.boundary,
+ getActiveDataOwnerPushStamp: () => ({ dataOwnerId: 'owner-a', ownerGeneration: 1 }),
+}));
+vi.mock('../../localDb/client/current', () => ({ getDbClient: () => ({ drizzle: mocks.db }) }));
+vi.mock('../../deepLink', () => ({
+ focusMainWindow: vi.fn(),
+ sendMainWindowMessage: vi.fn(),
+ getDeepLinkMainWindow: () => mocks.main,
+}));
+vi.mock('../../logger', () => ({ createLogger: () => ({ info: vi.fn() }) }));
+import { handOffScreenshotToTask, registerScreenshotComposeIpc } from '../compose';
+import { REGION_SCREENSHOT_COMPOSE_CHANNEL as C } from '../../../shared/regionScreenshot';
+
+// 测试价值:真实 handOff/TAKE 入口不补发过期动作,不接受其他窗口,异步入库不颠倒动作顺序。
+// 原来只有 renderer bus 覆盖;最小失败为等待 30s 后 TAKE,以及两次入库逆序完成。
+// tier: unit,存储与窗口用内存 fake。
+describe('screenshot compose delivery', () => {
+ const image = {
+ toPNG: () => Buffer.alloc(16),
+ getSize: () => ({ width: 2, height: 2 }),
+ } as NativeImage;
+ const event = { sender: mocks.main.webContents, senderFrame: mocks.main.webContents.mainFrame };
+ const take = () => mocks.handlers.get(C.TAKE)!(event);
+ beforeEach(() => {
+ vi.useFakeTimers();
+ mocks.scope = 'owner-a:1';
+ mocks.boundary = false;
+ mocks.ingest.mockClear();
+ registerScreenshotComposeIpc();
+ mocks.ingest.mockResolvedValue({ url: 'media:a', filename: 'a.png' });
+ });
+ afterEach(() => {
+ take();
+ vi.useRealTimers();
+ });
+ it('does not replay an automatic action when the main window opens much later', async () => {
+ await handOffScreenshotToTask(image, 'translate');
+ await vi.advanceTimersByTimeAsync(30_001);
+ expect(take()).toBeNull();
+ });
+ it('only lets the main frame take a request once', async () => {
+ await handOffScreenshotToTask(image, 'ask');
+ expect(mocks.handlers.get(C.TAKE)!({ ...event, senderFrame: {} })).toBeNull();
+ expect(take()).toMatchObject({ action: 'ask', url: 'media:a' });
+ expect(take()).toBeNull();
+ });
+ it('keeps the latest action when an older media write completes last', async () => {
+ let resolve!: (value: { url: string; filename: string }) => void;
+ mocks.ingest.mockReturnValueOnce(
+ new Promise((done) => {
+ resolve = done;
+ }),
+ );
+ const first = handOffScreenshotToTask(image, 'translate');
+ await handOffScreenshotToTask(image, 'explain');
+ resolve({ url: 'media:old', filename: 'old.png' });
+ await first;
+ expect(take()).toMatchObject({ action: 'explain', url: 'media:a' });
+ });
+ // Unit: owner changes at ingestion or delivery must never export an old account's image.
+ it.each(['ingest', 'take', 'boundary', 'capture'] as const)('rejects stale ownership at %s', async (phase) => {
+ if (phase === 'capture') {
+ await handOffScreenshotToTask(image, 'ask', 'older-owner');
+ expect(mocks.ingest).not.toHaveBeenCalled();
+ } else if (phase === 'ingest') {
+ mocks.ingest.mockImplementationOnce(async (_params, db) => {
+ expect(db).toBe(mocks.db);
+ mocks.scope = 'owner-b:2';
+ return { url: 'media:old', filename: 'old.png' };
+ });
+ await handOffScreenshotToTask(image, 'translate');
+ } else {
+ await handOffScreenshotToTask(image, 'translate');
+ if (phase === 'take') mocks.scope = 'owner-b:2';
+ else mocks.boundary = true;
+ }
+ expect(take()).toBeNull();
+ });
+});
diff --git a/apps/desktop/src/main/region-screenshot/__tests__/liveCapture.test.ts b/apps/desktop/src/main/region-screenshot/__tests__/liveCapture.test.ts
new file mode 100644
index 0000000000..c1be506af7
--- /dev/null
+++ b/apps/desktop/src/main/region-screenshot/__tests__/liveCapture.test.ts
@@ -0,0 +1,62 @@
+import type { Display } from 'electron';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { SnapshotHelper } from '../snapshotHost';
+
+const mocks = vi.hoisted(() => ({ sources: vi.fn(), capture: vi.fn() }));
+vi.mock('electron', () => ({
+ desktopCapturer: { getSources: mocks.sources },
+ nativeImage: {},
+ screen: { dipToScreenRect: (_window: unknown, rect: unknown) => rect },
+}));
+vi.mock('../../remote-desktop/nativeCapture', () => ({ NativeDesktopCapture: class {} }));
+import { captureLiveRegion, RegionVideoCapture } from '../liveCapture';
+
+const display = { id: 1, bounds: { x: 0, y: 0, width: 100, height: 200 }, scaleFactor: 2 } as Display;
+const selection = { x: 10, y: 20, width: 30, height: 40 };
+const crop = vi.fn();
+function bitmap(width: number, height: number) {
+ return {
+ isEmpty: () => false,
+ getSize: () => ({ width, height }),
+ crop: (rect: { width: number; height: number }) => { crop(rect); return bitmap(rect.width, rect.height); },
+ resize: (size: { width: number; height: number }) => bitmap(size.width, size.height),
+ toBitmap: () => Buffer.alloc(width * height * 4),
+ };
+}
+const helper = { capture: mocks.capture } as unknown as SnapshotHelper;
+// Unit: exercise the real capture entry after a dead optional helper. The window
+// suite mocks this module itself, so it cannot cover backend fallback or cancellation.
+// Minimum failure: helper returns null, but Electron still offers the selected screen.
+describe('live region capture recovery', () => {
+ beforeEach(() => {
+ vi.stubGlobal('process', Object.create(process, { platform: { value: 'win32' } }));
+ vi.clearAllMocks();
+ mocks.capture.mockResolvedValue(null);
+ mocks.sources.mockResolvedValue([{ display_id: '1', thumbnail: bitmap(200, 400) }]);
+ });
+ afterEach(() => vi.unstubAllGlobals());
+ it.each(['scroll', 'video', 'gif'] as const)('recovers %s capture and only returns the selected pixels', async mode => {
+ const recording = new RegionVideoCapture(helper);
+ const frame = mode === 'scroll'
+ ? await captureLiveRegion(display, selection, mode, helper)
+ : await recording.frame(display, selection, mode);
+ expect({ width: frame.width, height: frame.height, bytes: frame.data.byteLength })
+ .toEqual({ width: 60, height: 80, bytes: 60 * 80 * 4 });
+ expect(crop).toHaveBeenCalledWith({ x: 20, y: 40, width: 60, height: 80 });
+ recording.stop();
+ });
+ it('never substitutes another display and can recover on the next request', async () => {
+ mocks.sources.mockResolvedValueOnce([{ display_id: '2', thumbnail: bitmap(200, 400) }]);
+ await expect(captureLiveRegion(display, selection, 'scroll', helper)).rejects.toThrow('Display capture unavailable');
+ await expect(captureLiveRegion(display, selection, 'scroll', helper)).resolves.toMatchObject({ width: 60, height: 80 });
+ });
+ it('drops a Windows frame completed after recording stops', async () => {
+ let resolve!: (value: null) => void;
+ mocks.capture.mockReturnValueOnce(new Promise<null>(done => { resolve = done; }));
+ const recording = new RegionVideoCapture(helper);
+ const frame = recording.frame(display, selection, 'video');
+ recording.stop();
+ resolve(null);
+ await expect(frame).rejects.toThrow('Region capture unavailable');
+ });
+});
diff --git a/apps/desktop/src/main/region-screenshot/__tests__/recordingClipboard.test.ts b/apps/desktop/src/main/region-screenshot/__tests__/recordingClipboard.test.ts
new file mode 100644
index 0000000000..0f6e3e868a
--- /dev/null
+++ b/apps/desktop/src/main/region-screenshot/__tests__/recordingClipboard.test.ts
@@ -0,0 +1,117 @@
+import { afterEach, beforeEach, expect, it, vi } from 'vitest';
+import { copyRegionRecording } from '../recordingClipboard';
+import { saveRegionRecording } from '../save';
+import path from 'node:path';
+
+const mock = vi.hoisted(() => ({
+ exec: vi.fn(), put: vi.fn(), cleanup: vi.fn(), rollback: vi.fn(), current: vi.fn(),
+ saveDialog: vi.fn(), write: vi.fn(),
+}));
+vi.mock('electron', () => ({ app: { getPath: () => 'videos' }, dialog: { showSaveDialog: mock.saveDialog, showMessageBox: vi.fn() } }));
+vi.mock('node:fs/promises', () => ({ default: { writeFile: mock.write } }));
+vi.mock('../../i18n', () => ({ t: (key: string) => key }));
+vi.mock('node:child_process', () => ({ execFile: mock.exec }));
+vi.mock('../../cindy-media/integrationCache', () => ({ integrationCachePut: mock.put }));
+vi.mock('../../cindy-media/ledger', () => ({ removeRefsExceptHash: mock.cleanup }));
+vi.mock('../../localDb/client/current', () => ({ getCurrentDbClientSnapshot: mock.current }));
+vi.mock('../../device-link/broadcast-tap', () => ({ captureDataOwnerBroadcastScope: () => ({}), isDataOwnerBroadcastScopeCurrent: () => true }));
+vi.mock('../../logger', () => ({ createLogger: () => ({ warn: vi.fn() }) }));
+
+const gif = new Uint8Array([...Buffer.from('GIF89a'), ...new Uint8Array(15), 0x3b]);
+const db = {};
+const owner = { client: { drizzle: db } };
+const media = { absPath: "C:\\recordings\\a'b $x `name`.gif", hash: 'hash', rollbackRef: mock.rollback };
+
+beforeEach(() => {
+ vi.resetAllMocks();
+ vi.stubGlobal('process', Object.create(process, { platform: { value: 'win32' } }));
+ mock.current.mockReturnValue(owner);
+ mock.put.mockResolvedValue(media);
+ mock.cleanup.mockResolvedValue(1);
+ mock.rollback.mockResolvedValue(undefined);
+ mock.exec.mockImplementation((_file, _args, _options, callback) => callback(null));
+});
+afterEach(() => vi.unstubAllGlobals());
+
+// User-requested clipboard export: saving tests cannot cover native file formats
+// or retention after preview close. Production entry copyRegionRecording must
+// retain verified bytes, publish a file list, then release only its previous ref.
+// Minimal failures: invalid bytes, OS rejection, or owner replacement during ingest.
+// Tier: unit; real validation and native-command builder, injected OS/storage I/O.
+it('copies a retained file on Windows, escaping the path and cleaning old refs only after success', async () => {
+ await copyRegionRecording(gif, 'gif', () => true);
+ expect(mock.put).toHaveBeenCalledWith(expect.objectContaining({
+ buffer: gif, mimeType: 'image/gif', isCache: false,
+ cacheKey: 'recording-clipboard:latest', assertStillValid: expect.any(Function),
+ }), db);
+ expect(mock.exec).toHaveBeenCalledWith('powershell', [
+ '-NoProfile', '-NonInteractive', '-Command',
+ "$ErrorActionPreference = 'Stop'; Set-Clipboard -LiteralPath 'C:\\recordings\\a''b $x `name`.gif'",
+ ], expect.objectContaining({ windowsHide: true, timeout: 10_000 }), expect.any(Function));
+ expect(mock.cleanup).toHaveBeenCalledWith({ refKind: 'integration-cache', refId: 'recording-clipboard:latest', keepHash: 'hash' }, db);
+ expect(mock.exec.mock.invocationCallOrder[0]).toBeLessThan(mock.cleanup.mock.invocationCallOrder[0]);
+ expect(mock.rollback).not.toHaveBeenCalled();
+});
+
+it('passes the macOS file path as an argument rather than AppleScript source', async () => {
+ vi.stubGlobal('process', Object.create(process, { platform: { value: 'darwin' } }));
+ await copyRegionRecording(gif, 'gif', () => true);
+ expect(mock.exec).toHaveBeenCalledWith('osascript', [
+ '-e', 'on run argv', '-e', 'set the clipboard to (POSIX file (item 1 of argv))', '-e', 'end run', media.absPath,
+ ], expect.any(Object), expect.any(Function));
+});
+
+it('rolls back only the failed copy reference and permits retry with the same clip', async () => {
+ mock.exec.mockImplementationOnce((_file, _args, _options, callback) => callback(new Error('clipboard busy')));
+ await expect(copyRegionRecording(gif, 'gif', () => true)).rejects.toThrow('clipboard busy');
+ expect(mock.rollback).toHaveBeenCalledTimes(1);
+ expect(mock.cleanup).not.toHaveBeenCalled();
+ await copyRegionRecording(gif, 'gif', () => true);
+ expect(mock.cleanup).toHaveBeenCalledTimes(1);
+});
+
+it.each(['owner', 'preview'])('rejects a late clipboard write after %s changes', async (change) => {
+ let active = true;
+ mock.put.mockImplementationOnce(async () => {
+ if (change === 'owner') mock.current.mockReturnValue({ ...owner });
+ else active = false;
+ return media;
+ });
+ await expect(copyRegionRecording(gif, 'gif', () => active)).rejects.toThrow('cancelled');
+ expect(mock.exec).not.toHaveBeenCalled();
+ expect(mock.rollback).toHaveBeenCalledTimes(1);
+ expect(mock.cleanup).not.toHaveBeenCalled();
+});
+
+it('rejects invalid media before storage or clipboard access', async () => {
+ await expect(copyRegionRecording(gif, 'webm', () => true)).rejects.toThrow('Invalid recording');
+ await expect(copyRegionRecording(new Uint8Array(20), 'gif', () => true)).rejects.toThrow('Invalid recording');
+ expect(mock.put).not.toHaveBeenCalled();
+ expect(mock.exec).not.toHaveBeenCalled();
+});
+
+it('keeps successful clipboard bytes referenced if old-reference cleanup fails', async () => {
+ mock.cleanup.mockRejectedValueOnce(new Error('DB unavailable'));
+ await expect(copyRegionRecording(gif, 'gif', () => true)).resolves.toBeUndefined();
+ expect(mock.rollback).not.toHaveBeenCalled();
+});
+
+// PR #7300 owner boundary: clipboard tests do not cover the native save dialog.
+// Unit, real save entry: invalidate while the dialog is pending; no old clip may
+// be written to the newly selected path. Reuse this export suite and fake only I/O.
+it('cancels recording export when ownership changes before the save dialog returns', async () => {
+ let current = true;
+ const filePath = path.join('recordings', 'clip.gif');
+ mock.saveDialog.mockImplementationOnce(async () => {
+ current = false;
+ return { canceled: false, filePath };
+ });
+ expect(await saveRegionRecording(gif, 'gif', () => current)).toBe(false);
+ expect(mock.write).not.toHaveBeenCalled();
+ expect(await saveRegionRecording(gif, 'gif', () => current)).toBe(false);
+ expect(mock.saveDialog).toHaveBeenCalledTimes(1);
+ current = true;
+ mock.saveDialog.mockResolvedValueOnce({ canceled: false, filePath });
+ expect(await saveRegionRecording(gif, 'gif', () => current)).toBe(true);
+ expect(mock.write).toHaveBeenCalledExactlyOnceWith(filePath, gif);
+});
diff --git a/apps/desktop/src/main/region-screenshot/__tests__/snapshotHost.test.ts b/apps/desktop/src/main/region-screenshot/__tests__/snapshotHost.test.ts
new file mode 100644
index 0000000000..9a595b4700
--- /dev/null
+++ b/apps/desktop/src/main/region-screenshot/__tests__/snapshotHost.test.ts
@@ -0,0 +1,117 @@
+import { EventEmitter } from 'node:events';
+import { PassThrough } from 'node:stream';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({ spawn: vi.fn() }));
+vi.mock('electron', () => ({ app: { isPackaged: true } }));
+vi.mock('node:child_process', async (original) => ({
+ ...(await original<typeof import('node:child_process')>()),
+ spawn: mocks.spawn,
+}));
+vi.mock('../../logger', () => ({ createLogger: () => ({ warn: vi.fn() }) }));
+import { SnapshotHelper } from '../snapshotHost';
+
+// 测试价值:真实 SnapshotHelper 请求入口在管道断开/超时时降级,不让 Cindy 崩溃。
+// 原先没有 helper 覆盖;最小失败输入是 stdin error 事件,unit 使用内存流和假时钟。
+describe('snapshot helper failure isolation', () => {
+ let child: EventEmitter & {
+ stdin: PassThrough;
+ stdout: PassThrough;
+ stderr: PassThrough;
+ exitCode: null;
+ kill: ReturnType<typeof vi.fn>;
+ };
+ let helper: SnapshotHelper;
+ beforeEach(async () => {
+ vi.useFakeTimers();
+ // This suite models a packaged Windows helper, independent of the CI host.
+ // Linux intentionally returns no helper; test that separate branch below.
+ vi.stubGlobal('process', Object.defineProperties(Object.create(process), {
+ resourcesPath: { value: 'resources' },
+ platform: { value: 'win32' },
+ }));
+ child = Object.assign(new EventEmitter(), {
+ stdin: new PassThrough(),
+ stdout: new PassThrough(),
+ stderr: new PassThrough(),
+ exitCode: null,
+ kill: vi.fn(),
+ });
+ mocks.spawn.mockReturnValue(child);
+ helper = await SnapshotHelper.start();
+ });
+ afterEach(() => {
+ helper?.dispose();
+ vi.useRealTimers();
+ vi.unstubAllGlobals();
+ });
+
+ it('settles pending requests on pipe errors and tolerates late errors after disposal', async () => {
+ const result = helper.windows();
+ expect(() =>
+ child.stdin.emit('error', Object.assign(new Error('closed'), { code: 'EPIPE' })),
+ ).not.toThrow();
+ await expect(result).resolves.toEqual([]);
+ expect(child.kill).toHaveBeenCalledTimes(1);
+ expect(() => child.stdin.emit('error', new Error('late'))).not.toThrow();
+ await expect(helper.windows()).resolves.toEqual([]);
+ });
+
+ it('degrades when writing throws synchronously', async () => {
+ vi.spyOn(child.stdin, 'write').mockImplementation(() => {
+ throw new Error('closed');
+ });
+ await expect(helper.windows()).resolves.toEqual([]);
+ });
+
+ it('bounds a stuck helper instead of accumulating timed-out queries', async () => {
+ const result = helper.windows();
+ await vi.advanceTimersByTimeAsync(1500);
+ await expect(result).resolves.toEqual([]);
+ expect(child.kill).toHaveBeenCalledTimes(1);
+ await expect(helper.windows()).resolves.toEqual([]);
+ });
+
+ it('accepts valid geometry and ignores malformed replies', async () => {
+ const result = helper.windows();
+ child.stdout.write('not json\n');
+ child.stdout.write('null\n[]\n');
+ child.stdout.write(
+ JSON.stringify({
+ id: 1,
+ windows: [
+ { hwnd: 5, pid: 9, rect: [0, 0, 20, 30] },
+ { hwnd: 6, rect: [0, 0, -1, 2] },
+ ],
+ }) + '\n',
+ );
+ await expect(result).resolves.toEqual([{ handle: 5, pid: 9, rect: [0, 0, 20, 30] }]);
+ });
+
+ // Unit: the production start entry on unsupported platforms must keep screen
+ // capture optional, without attempting to spawn the Windows helper binary.
+ it('does not start a native helper on an unsupported platform', async () => {
+ vi.stubGlobal('process', Object.defineProperty(Object.create(process), 'platform', { value: 'linux' }));
+ mocks.spawn.mockClear();
+ const unsupported = await SnapshotHelper.start();
+ expect(mocks.spawn).not.toHaveBeenCalled();
+ await expect(unsupported.windows()).resolves.toEqual([]);
+ await expect(unsupported.capture({ x: 0, y: 0, width: 2, height: 2 }, 960)).resolves.toBeNull();
+ unsupported.dispose();
+ });
+
+ // Native video now supplies bytes instead of geometry. A truncated or oversized
+ // frame must never reach canvas/IPC; exercise the actual child response path.
+ it('accepts bounded native BGRA pixels and rejects inconsistent frame replies', async () => {
+ const rect = { x: -100, y: 20, width: 2, height: 2 };
+ const good = helper.capture(rect, 960);
+ child.stdout.write(JSON.stringify({ id: 1, width: 2, height: 2, pixels: Buffer.alloc(16, 255).toString('base64') }) + '\n');
+ await expect(good).resolves.toEqual({ width: 2, height: 2, data: new Uint8Array(16).fill(255) });
+ const short = helper.capture(rect, 960);
+ child.stdout.write(JSON.stringify({ id: 2, width: 2, height: 2, pixels: 'AAAA' }) + '\n');
+ await expect(short).resolves.toBeNull();
+ const oversized = helper.capture(rect, 960);
+ child.stdout.write(JSON.stringify({ id: 3, width: 961, height: 2, pixels: '' }) + '\n');
+ await expect(oversized).resolves.toBeNull();
+ });
+});
diff --git a/apps/desktop/src/main/region-screenshot/__tests__/startup.test.ts b/apps/desktop/src/main/region-screenshot/__tests__/startup.test.ts
new file mode 100644
index 0000000000..43ca9e2ff4
--- /dev/null
+++ b/apps/desktop/src/main/region-screenshot/__tests__/startup.test.ts
@@ -0,0 +1,136 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+const mocks = vi.hoisted(() => ({
+ shortcut: null as (() => void) | null,
+ capture: vi.fn(),
+ start: vi.fn(),
+ dispose: vi.fn(),
+ windows: vi.fn(async () => []),
+ frontmostPid: vi.fn(async () => null),
+ activeSession: null as null | { close: () => void },
+}));
+vi.mock('electron', () => ({
+ app: {},
+ clipboard: {},
+ desktopCapturer: { getSources: mocks.capture },
+ dialog: { showMessageBox: vi.fn() },
+ globalShortcut: {
+ register: (_key: string, callback: () => void) => {
+ mocks.shortcut = callback;
+ return true;
+ },
+ unregister: vi.fn(),
+ },
+ ipcMain: { on: vi.fn(), handle: vi.fn() },
+ screen: {
+ on: vi.fn(),
+ removeListener: vi.fn(),
+ getAllDisplays: () => [{ id: 1, bounds: { width: 10, height: 10 }, scaleFactor: 1 }],
+ },
+ shell: {},
+ systemPreferences: { getMediaAccessStatus: () => 'granted' },
+}));
+vi.mock('../../logger', () => ({ createLogger: () => ({ info: vi.fn(), warn: vi.fn() }) }));
+vi.mock('../../appSessionState', () => ({ activeOwnerScopeKey: () => 'owner-a:1', isAppSessionBoundaryPending: () => false, onAppSessionInvalidated: () => () => {} }));
+vi.mock('../../i18n', () => ({ t: (key: string) => key }));
+vi.mock('../../app-shortcuts', () => ({
+ getAppShortcutStore: () => ({
+ subscribe: () => () => {},
+ getEffectiveCombos: () => ['screenshot'],
+ }),
+ setGlobalShortcutRegistrationFailures: vi.fn(),
+ subscribeAppShortcutRecording: () => () => {},
+}));
+vi.mock('../../../shared/appShortcuts', () => ({ comboToElectronAccelerator: () => 'Ctrl+Alt+S' }));
+vi.mock('../../remote-desktop/captureSource', () => ({
+ enumerateDesktopSources: (fn: () => unknown) => fn(),
+}));
+vi.mock('../../computer-permission-guide/request', () => ({
+ MAC_SCREEN_RECORDING_SETTINGS_URL: '',
+}));
+vi.mock('../compose', () => ({
+ handOffScreenshotToTask: vi.fn(),
+ registerScreenshotComposeIpc: vi.fn(),
+}));
+vi.mock('../pins', () => ({ closeAllPins: vi.fn(), openPin: vi.fn(), registerPinIpc: vi.fn() }));
+vi.mock('../save', () => ({ saveScreenshotImage: vi.fn() }));
+vi.mock('../overlays', () => ({
+ OverlayPool: class {
+ isDisabled = false;
+ setGoneHandler() {}
+ reset() {}
+ prewarm() {}
+ destroyAll() {}
+ },
+}));
+vi.mock('../snapshotHost', () => ({
+ SnapshotHelper: { start: mocks.start },
+ resolveSnapshotBinary: vi.fn(),
+}));
+vi.mock('../session', () => ({
+ RegionScreenshotSession: class {
+ constructor(private deps: { onClosed: () => void }) {
+ mocks.activeSession = this;
+ }
+ open = async () => true;
+ close() {
+ this.deps.onClosed();
+ }
+ },
+}));
+import { initRegionScreenshot, stopRegionScreenshot } from '../index';
+
+// 测试价值:从真实快捷键启动入口验证失败和晚到 helper 的释放,填补原先启动编排零覆盖。
+// 最小失败输入为 capture reject 早于 helper resolve;tier: unit,假定时器和内存依赖。
+describe('screenshot startup cleanup', () => {
+ const helper = {
+ dispose: mocks.dispose,
+ windows: mocks.windows,
+ frontmostPid: mocks.frontmostPid,
+ };
+ beforeEach(() => {
+ vi.useFakeTimers();
+ vi.clearAllMocks();
+ mocks.start.mockResolvedValue(helper);
+ mocks.capture.mockResolvedValue([]);
+ initRegionScreenshot();
+ });
+ afterEach(() => {
+ stopRegionScreenshot();
+ vi.useRealTimers();
+ });
+ it('releases the helper when capturing fails', async () => {
+ mocks.capture.mockRejectedValueOnce(new Error('capture failed'));
+ mocks.shortcut!();
+ await vi.advanceTimersByTimeAsync(0);
+ expect(mocks.dispose).toHaveBeenCalledTimes(1);
+ });
+ it('releases a helper arriving after capture has already failed', async () => {
+ let resolve!: (value: typeof helper) => void;
+ mocks.start.mockReturnValueOnce(
+ new Promise((done) => {
+ resolve = done;
+ }),
+ );
+ mocks.capture.mockRejectedValueOnce(new Error('capture failed'));
+ mocks.shortcut!();
+ await vi.advanceTimersByTimeAsync(0);
+ resolve(helper);
+ await vi.advanceTimersByTimeAsync(0);
+ expect(mocks.dispose).toHaveBeenCalledTimes(1);
+ });
+ it('requests nonblocking helper startup and releases it on an empty capture', async () => {
+ mocks.shortcut!();
+ await vi.advanceTimersByTimeAsync(0);
+ expect(mocks.start).toHaveBeenCalledWith(false);
+ expect(mocks.dispose).toHaveBeenCalledTimes(1);
+ });
+ it('keeps the helper until the successfully opened screenshot closes', async () => {
+ mocks.capture.mockResolvedValueOnce([{ display_id: '1', thumbnail: { isEmpty: () => false } }]);
+ mocks.shortcut!();
+ await vi.advanceTimersByTimeAsync(0);
+ expect(mocks.dispose).not.toHaveBeenCalled();
+ mocks.activeSession!.close();
+ await vi.advanceTimersByTimeAsync(0);
+ expect(mocks.dispose).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/apps/desktop/src/main/region-screenshot/__tests__/windows.test.ts b/apps/desktop/src/main/region-screenshot/__tests__/windows.test.ts
new file mode 100644
index 0000000000..9fab80296a
--- /dev/null
+++ b/apps/desktop/src/main/region-screenshot/__tests__/windows.test.ts
@@ -0,0 +1,861 @@
+import { EventEmitter } from 'node:events';
+import type { BrowserWindow, Display, NativeImage } from 'electron';
+import type { SnapshotHelper } from '../snapshotHost';
+import type { RegionRect, RegionScreenshotBitmap } from '../../../shared/regionScreenshot';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+ ownerScope: 'owner-a:1',
+ boundary: false,
+ invalidations: new Set<() => void>(),
+ switches: new Set<string>(),
+ create: vi.fn(),
+ focus: vi.fn(),
+ screen: new (class {
+ on = vi.fn();
+ removeListener = vi.fn();
+ getAllDisplays = vi.fn();
+ getDisplayMatching = (bounds: unknown) => ({ workArea: bounds });
+ getCursorScreenPoint = () => ({ x: 20, y: 20 });
+ dipToScreenPoint = (point: unknown) => point;
+ screenToDipRect = (_window: unknown, rect: unknown) => rect;
+ })(),
+ handlers: new Map<string, (...args: unknown[]) => unknown>(),
+ register: vi.fn<(key: string, callback: () => void) => boolean>(() => true),
+ unregister: vi.fn(),
+ liveCapture: vi.fn(),
+ saveRecording: vi.fn(async () => true),
+ copyRecording: vi.fn<(bytes: Uint8Array, format: string, isCurrent: () => boolean) => Promise<void>>(async () => {}),
+}));
+vi.mock('electron', () => ({
+ app: {
+ focus: mocks.focus,
+ commandLine: {
+ hasSwitch: (flag: string) => mocks.switches.has(flag),
+ appendSwitch: (flag: string) => { mocks.switches.add(flag); },
+ removeSwitch: (flag: string) => { mocks.switches.delete(flag); },
+ },
+ },
+ clipboard: { writeImage: vi.fn(), writeText: vi.fn() },
+ screen: mocks.screen,
+ nativeTheme: { shouldUseDarkColors: false },
+ globalShortcut: { register: mocks.register, unregister: mocks.unregister },
+ systemPreferences: { isTrustedAccessibilityClient: () => true },
+ nativeImage: {
+ createFromBitmap: (
+ data: Buffer,
+ options: { width: number; height: number; scaleFactor: number },
+ ) => ({
+ // Electron ImageSkiaRep.GetWidth/GetHeight 返回 DIP,而 toBitmap 返回物理像素。
+ getSize: () => ({
+ width: options.width / options.scaleFactor,
+ height: options.height / options.scaleFactor,
+ }),
+ toBitmap: () => data,
+ isEmpty: () => false,
+ }),
+ },
+ Menu: { buildFromTemplate: vi.fn() },
+ ipcMain: { on: (name: string, fn: (...args: unknown[]) => unknown) => mocks.handlers.set(name, fn), handle: (name: string, fn: (...args: unknown[]) => unknown) => mocks.handlers.set(name, fn) },
+}));
+vi.mock('../../appSessionState', () => ({
+ activeOwnerScopeKey: () => mocks.ownerScope,
+ isAppSessionBoundaryPending: () => mocks.boundary,
+ onAppSessionInvalidated: (listener: () => void) => {
+ mocks.invalidations.add(listener);
+ return () => { mocks.invalidations.delete(listener); };
+ },
+}));
+vi.mock('../pageWindow', () => ({ createScreenshotPageWindow: mocks.create }));
+vi.mock('../compose', () => ({ handOffScreenshotToTask: vi.fn() }));
+vi.mock('../save', () => ({ saveScreenshotImage: vi.fn(), saveRegionRecording: mocks.saveRecording }));
+vi.mock('../recordingClipboard', () => ({ copyRegionRecording: mocks.copyRecording }));
+vi.mock('../liveCapture', () => ({ captureLiveRegion: mocks.liveCapture, RegionVideoCapture: class { frame = mocks.liveCapture; stop() {} } }));
+vi.mock('../../i18n', () => ({ getResolvedMainLocale: () => 'en', t: (key: string) => key }));
+vi.mock('../../logger', () => ({ createLogger: () => ({ warn: vi.fn(), info: vi.fn(), error: vi.fn() }) }));
+import { OverlayPool, hideScreenshotOverlay, showScreenshotOverlay } from '../overlays';
+import { RegionScreenshotSession } from '../session';
+import { acquireOverlayEscape } from '../../overlayEscape';
+import { closeAllPins, openPin, registerPinIpc } from '../pins';
+import { ScreenshotEditor } from '../editor';
+import { RecordingPreview } from '../recordingPreview';
+import { RECORDING_PREVIEW_CHANNEL as R } from '../../../shared/regionCapture';
+import { REGION_SCREENSHOT_EDITOR_CHANNEL as E, REGION_SCREENSHOT_PIN_CHANNEL as P } from '../../../shared/regionScreenshot';
+
+let nextId = 0;
+function fakeWindow() {
+ let destroyed = false;
+ let visible = false;
+ const window = Object.assign(new EventEmitter(), {
+ webContents: Object.assign(new EventEmitter(), {
+ id: ++nextId,
+ mainFrame: {},
+ isDestroyed: () => destroyed,
+ send: vi.fn(),
+ sendInputEvent: vi.fn(),
+ }),
+ isFocused: vi.fn(() => false),
+ isMinimized: () => false, isMaximized: () => false, isFullScreen: () => false,
+ setTitle: vi.fn(),
+ minimize: vi.fn(),
+ show: vi.fn(() => { visible = true; window.emit('show'); }),
+ isDestroyed: () => destroyed,
+ isVisible: () => visible,
+ setVisibleOnAllWorkspaces: vi.fn(),
+ setAlwaysOnTop: vi.fn(),
+ setBounds: vi.fn(),
+ setOpacity: vi.fn(),
+ setIgnoreMouseEvents: vi.fn(),
+ focus: vi.fn(),
+ blur: vi.fn(),
+ showInactive: vi.fn(() => {
+ visible = true;
+ window.emit('show');
+ }),
+ hide: vi.fn(() => {
+ visible = false;
+ window.emit('hide');
+ }),
+ destroy: vi.fn(() => {
+ destroyed = true;
+ window.emit('closed');
+ }),
+ close: vi.fn(() => window.destroy()),
+ });
+ return window;
+}
+const display = {
+ id: 1,
+ bounds: { x: 0, y: 0, width: 100, height: 100 },
+ scaleFactor: 2,
+} as Display;
+const image = {
+ getSize: () => ({ width: 2, height: 2 }),
+ toBitmap: () => Buffer.alloc(16),
+} as NativeImage;
+
+// 测试价值:OverlayPool/Session/openPin 的真实入口保护首帧、故障退出和 IPC 来源。
+// 旧代码没有窗口生命周期测试;最小输入为 unresponsive、未 PAINTED、2x 位图和 workArea 事件。
+// tier: unit;Electron 由内存窗口替代,全部时序用假时钟。
+describe('screenshot window lifecycle', () => {
+ let pool: OverlayPool;
+ let windows: ReturnType<typeof fakeWindow>[];
+ beforeEach(() => {
+ vi.useFakeTimers();
+ vi.clearAllMocks();
+ mocks.switches.clear();
+ mocks.ownerScope = 'owner-a:1';
+ mocks.boundary = false;
+ windows = [];
+ mocks.create.mockImplementation(() => {
+ const window = fakeWindow();
+ windows.push(window);
+ return window;
+ });
+ mocks.screen.getAllDisplays.mockReturnValue([display]);
+ pool = new OverlayPool();
+ });
+ afterEach(() => {
+ pool.destroyAll();
+ closeAllPins();
+ vi.useRealTimers();
+ vi.unstubAllGlobals();
+ });
+
+ // 用户反馈:打开截图时整屏缩放。实机验证 Aura 动画;unit 保护临时开关
+ // 不泄漏到其它窗口、不清除用户启动参数,且异常也恢复。tier: unit。
+ it.each([
+ ['win32', false, false],
+ ['win32', false, true],
+ ['win32', true, false],
+ ['darwin', false, false],
+ ] as const)('scopes screenshot animations on %s (existing=%s, throws=%s)', (platform, existing, throws) => {
+ vi.stubGlobal('process', Object.create(process, { platform: { value: platform } }));
+ const flag = 'wm-window-animations-disabled';
+ if (existing) mocks.switches.add(flag);
+ // 隐藏也必须禁用动画,否则第二次显示仍保留 Aura 的透明层。
+ for (const changeVisibility of [showScreenshotOverlay, hideScreenshotOverlay]) {
+ let disabledDuringChange: boolean | undefined;
+ const change = () => {
+ disabledDuringChange = mocks.switches.has(flag);
+ if (throws) throw new Error('window destroyed');
+ };
+ const window = { showInactive: change, hide: change } as BrowserWindow;
+ if (throws) expect(() => changeVisibility(window)).toThrow('window destroyed');
+ else changeVisibility(window);
+ expect(disabledDuringChange).toBe(platform === 'win32');
+ expect(mocks.switches.has(flag)).toBe(existing);
+ }
+ });
+
+ // User report (macOS): the mode bar sat under the notch and live controls over the Dock.
+ // The page only learns its chrome area from BEGIN; recording controls are placed in main.
+ // Minimal input: a work area without menu bar / Dock plus a 32pt notch. tier: unit.
+ it('gives macOS overlays a notch- and Dock-free chrome area for the toolbar and live controls', async () => {
+ vi.stubGlobal('process', Object.create(process, { platform: { value: 'darwin' } }));
+ const notched = { ...display, bounds: { x: 0, y: 0, width: 1470, height: 956 }, workArea: { x: 0, y: 24, width: 1470, height: 862 }, scaleFactor: 1 } as Display;
+ mocks.screen.getAllDisplays.mockReturnValue([notched]);
+ const overlay = pool.ensure(notched)!;
+ const owner = overlay.window.webContents;
+ pool.markShellReady(owner, owner.mainFrame);
+ const cropped = { getSize: () => ({ width: 400, height: 300 }), toBitmap: () => Buffer.alloc(400 * 300 * 4), resize: () => cropped };
+ const source = { getSize: () => ({ width: 1470, height: 956 }), toBitmap: () => Buffer.alloc(1470 * 956 * 4), crop: () => cropped } as unknown as NativeImage;
+ const helper = {} as SnapshotHelper;
+ const session = new RegionScreenshotSession({ pool, captures: [{ display: notched, image: source }], helper, windows: [], lastRegions: new Map(), topInsets: new Map([[notched.id, 32]]), onClosed: vi.fn(), onResult: vi.fn() });
+ await session.open();
+ const begin = vi.mocked(owner.send).mock.calls.find(([name]) => name === 'region-screenshot:begin')![1];
+ expect(begin.safeArea).toEqual({ x: 0, y: 32, width: 1470, height: 854 });
+ session.painted(owner, owner.mainFrame, session.token);
+ const selected = { x: 200, y: 300, width: 700, height: 530 };
+ const live = session.startLive(owner, owner.mainFrame, session.token, 'video', selected)!;
+ const controls = live.recordingLayout!.controls;
+ expect(controls.y).toBeGreaterThanOrEqual(32);
+ expect(controls.y + controls.height).toBeLessThanOrEqual(886);
+ session.close();
+ });
+
+ // Phase 5/6: same trusted sender/token contract now guards continuing capture and clip export.
+ // Existing static-image tests cannot observe a late frame after cancellation or native-dialog retry.
+ // Minimal input: one live request, close before the capture promise resolves. tier: unit.
+ it('rejects foreign live requests, drops late pixels after cancellation, and never starts key sampling by default', async () => {
+ const largeDisplay = { ...display, bounds: { x: 0, y: 0, width: 1280, height: 900 }, scaleFactor: 1 };
+ mocks.screen.getAllDisplays.mockReturnValue([largeDisplay]);
+ const overlay = pool.ensure(largeDisplay)!;
+ const owner = overlay.window.webContents;
+ pool.markShellReady(owner, owner.mainFrame);
+ const cropped = { getSize: () => ({ width: 400, height: 300 }), toBitmap: () => Buffer.alloc(400 * 300 * 4), resize: () => cropped };
+ const source = { getSize: () => ({ width: 1280, height: 900 }), toBitmap: () => Buffer.alloc(1280 * 900 * 4), crop: () => cropped } as unknown as NativeImage;
+ const keys = vi.fn(async () => ['Ctrl', 'C']);
+ const session = new RegionScreenshotSession({ pool, captures: [{ display: largeDisplay, image: source }], helper: { keys } as unknown as SnapshotHelper, windows: [], lastRegions: new Map(), onClosed: vi.fn(), onResult: vi.fn() });
+ await session.open();
+ session.painted(owner, owner.mainFrame, session.token);
+ const selected = { x: 0, y: 0, width: 400, height: 300 };
+ expect(session.startLive(owner, {} as Electron.WebFrameMain, session.token, 'video', selected)).toBeNull();
+ expect(session.startLive(owner, owner.mainFrame, 'stale', 'video', selected)).toBeNull();
+ expect(session.startLive(owner, owner.mainFrame, session.token, 'video', selected)?.mode).toBe('video');
+ let resolve!: (value: unknown) => void;
+ mocks.liveCapture.mockImplementationOnce(() => new Promise((done) => { resolve = done; }));
+ const pending = session.liveFrame(owner, owner.mainFrame, session.token, false);
+ expect(await session.liveFrame(owner, owner.mainFrame, session.token, true)).toBeNull();
+ session.close();
+ resolve({ width: 400, height: 300, data: new Uint8Array(400 * 300 * 4) });
+ expect(await pending).toBeNull();
+ expect(keys).not.toHaveBeenCalled();
+ expect(await session.liveFrame(owner, owner.mainFrame, session.token, true)).toBeNull();
+ expect(mocks.liveCapture).toHaveBeenCalledTimes(1);
+ });
+
+ // User regression: Edit restored a full-screen black overlay. A valid image must
+ // transfer to the independent editor and retire the capture; rejected images retain it. tier: unit.
+ it('hands the long image to a separate editor and retires the capture overlays', async () => {
+ const largeDisplay = { ...display, bounds: { x: 0, y: 0, width: 1280, height: 900 }, scaleFactor: 1 };
+ mocks.screen.getAllDisplays.mockReturnValue([largeDisplay]);
+ const overlay = pool.ensure(largeDisplay)!;
+ const owner = overlay.window.webContents;
+ pool.markShellReady(owner, owner.mainFrame);
+ const crop = { getSize: () => ({ width: 400, height: 300 }), toBitmap: () => Buffer.alloc(400 * 300 * 4), resize: () => crop };
+ const source = { getSize: () => ({ width: 1280, height: 900 }), toBitmap: () => Buffer.alloc(1280 * 900 * 4), crop: () => crop } as unknown as NativeImage;
+ const result = vi.fn();
+ const openEditor = vi.fn<(image: RegionScreenshotBitmap, display: Display, selection: RegionRect) => boolean>(() => true);
+ const session = new RegionScreenshotSession({ pool, captures: [{ display: largeDisplay, image: source }], helper: {} as SnapshotHelper, windows: [], lastRegions: new Map(), onClosed: vi.fn(), onResult: result, openEditor });
+ await session.open();
+ session.painted(owner, owner.mainFrame, session.token);
+ const selection = { x: 0, y: 0, width: 400, height: 300 };
+ session.startLive(owner, owner.mainFrame, session.token, 'scroll', selection);
+ expect(windows[0].setBounds).toHaveBeenLastCalledWith(largeDisplay.bounds, false);
+ expect(windows[0].setIgnoreMouseEvents).toHaveBeenLastCalledWith(true, { forward: true });
+ const long = { width: 400, height: 1500, data: new Uint8Array(400 * 1500 * 4) };
+ expect(session.restoreEditor(owner, owner.mainFrame, 'stale', long)).toBe(false);
+ expect(session.restoreEditor(owner, {} as Electron.WebFrameMain, session.token, long)).toBe(false);
+ expect(session.restoreEditor(owner, owner.mainFrame, session.token, { ...long, data: new Uint8Array(4) })).toBe(false);
+ expect(openEditor).not.toHaveBeenCalled();
+ openEditor.mockReturnValueOnce(false);
+ expect(session.restoreEditor(owner, owner.mainFrame, session.token, long)).toBe(false);
+ expect(session.isClosed).toBe(false);
+ expect(session.restoreEditor(owner, owner.mainFrame, session.token, long)).toBe(true);
+ // Assert byte ownership directly; serializing millions of typed-array entries
+ // in a call matcher made this lifecycle test time out on the Linux CI runner.
+ const handedOff = openEditor.mock.calls.at(-1)!;
+ expect({ width: handedOff[0].width, height: handedOff[0].height }).toEqual({ width: long.width, height: long.height });
+ expect(handedOff[0].data).toBe(long.data);
+ expect(handedOff[1]).toBe(largeDisplay);
+ expect(handedOff[2]).toEqual(selection);
+ expect(session.isClosed).toBe(true);
+ expect(session.hasEditor).toBe(true);
+ expect(windows[0].isVisible()).toBe(false);
+ expect(await session.liveFrame(owner, owner.mainFrame, session.token, false)).toBeNull();
+ expect(result).not.toHaveBeenCalled();
+ });
+
+ // Auto scrolling operates on the source app: stale tokens must never trigger it,
+ // and stopping while a frame is pending must prevent the next wheel event. tier: unit.
+ it('confines automatic scrolling to the owner and stops before a pending frame completes', async () => {
+ const largeDisplay = { ...display, bounds: { x: 0, y: 0, width: 1280, height: 900 }, scaleFactor: 1 };
+ mocks.screen.getAllDisplays.mockReturnValue([largeDisplay]);
+ const overlay = pool.ensure(largeDisplay)!;
+ const owner = overlay.window.webContents;
+ pool.markShellReady(owner, owner.mainFrame);
+ const bitmap = { width: 400, height: 300, data: new Uint8Array(400 * 300 * 4) };
+ const crop = { getSize: () => ({ width: 400, height: 300 }), toBitmap: () => Buffer.from(bitmap.data), resize: () => crop };
+ const source = { getSize: () => ({ width: 1280, height: 900 }), toBitmap: () => Buffer.alloc(1280 * 900 * 4), crop: () => crop } as unknown as NativeImage;
+ const scroll = vi.fn(async () => true);
+ const target = { handle: 99, pid: 1, rect: [0, 0, 1280, 900] as [number, number, number, number] };
+ const session = new RegionScreenshotSession({ pool, captures: [{ display: largeDisplay, image: source }], helper: { scroll } as unknown as SnapshotHelper, windows: [target], lastRegions: new Map(), onClosed: vi.fn(), onResult: vi.fn() });
+ await session.open();
+ session.painted(owner, owner.mainFrame, session.token);
+ session.startLive(owner, owner.mainFrame, session.token, 'scroll', { x: 100, y: 100, width: 400, height: 300 });
+ expect(session.autoScroll(owner, owner.mainFrame, 'stale', true)).toBe(false);
+ expect(session.autoScroll(owner, {} as Electron.WebFrameMain, session.token, true)).toBe(false);
+ expect(session.autoScroll(owner, owner.mainFrame, session.token, true)).toBe(true);
+ mocks.liveCapture.mockResolvedValueOnce(bitmap);
+ expect((await session.liveFrame(owner, owner.mainFrame, session.token, false))?.autoScrolling).toBe(true);
+ expect(scroll).toHaveBeenCalledExactlyOnceWith(target, 300, 250, -60);
+ await vi.advanceTimersByTimeAsync(200);
+ let resolve!: (value: unknown) => void;
+ mocks.liveCapture.mockImplementationOnce(() => new Promise(done => { resolve = done; }));
+ const pending = session.liveFrame(owner, owner.mainFrame, session.token, false);
+ session.holdCapture(owner, owner.mainFrame, session.token);
+ resolve(bitmap);
+ expect((await pending)?.autoScrolling).toBe(false);
+ expect(scroll).toHaveBeenCalledTimes(1);
+ session.close();
+ expect(session.autoScroll(owner, owner.mainFrame, session.token, true)).toBe(false);
+ expect(windows[0].setIgnoreMouseEvents).toHaveBeenLastCalledWith(false);
+ });
+
+ // 用户反馈开始录制时整屏抖动。Electron macOS 的 blur 会 orderOut 再 orderBack,
+ // 现有首帧测试未覆盖开始采集时的层级切换。最小输入:已显示的面板开始采集。
+ // tier: unit;内存窗口模拟原生 blur 的显隐,不能让采集开始重排正在显示的面板。
+ it.each(['video', 'gif', 'scroll'] as const)('keeps the macOS capture panel continuously visible when starting %s', async (mode) => {
+ vi.stubGlobal('process', Object.create(process, { platform: { value: 'darwin' } }));
+ const largeDisplay = { ...display, bounds: { x: 0, y: 0, width: 1280, height: 900 }, scaleFactor: 1 };
+ mocks.screen.getAllDisplays.mockReturnValue([largeDisplay]);
+ const overlay = pool.ensure(largeDisplay)!;
+ const owner = overlay.window.webContents;
+ pool.markShellReady(owner, owner.mainFrame);
+ const crop = { getSize: () => ({ width: 400, height: 300 }), toBitmap: () => Buffer.alloc(400 * 300 * 4), resize: () => crop };
+ const source = { getSize: () => ({ width: 1280, height: 900 }), toBitmap: () => Buffer.alloc(1280 * 900 * 4), crop: () => crop } as unknown as NativeImage;
+ const session = new RegionScreenshotSession({ pool, captures: [{ display: largeDisplay, image: source }], helper: {} as SnapshotHelper, windows: [], lastRegions: new Map(), onClosed: vi.fn(), onResult: vi.fn() });
+ try {
+ await session.open();
+ session.painted(owner, owner.mainFrame, session.token);
+ const win = windows[0], visibility: string[] = [];
+ win.on('hide', () => visibility.push('hide'));
+ win.on('show', () => visibility.push('show'));
+ win.blur.mockImplementation(() => { win.hide(); win.showInactive(); });
+ win.setBounds.mockClear();
+ expect(session.startLive(owner, owner.mainFrame, session.token, mode, { x: 100, y: 100, width: 400, height: 300 })).not.toBeNull();
+ expect(visibility).toEqual([]);
+ expect(win.isVisible()).toBe(true);
+ expect(win.setBounds).not.toHaveBeenCalled();
+ } finally { session.close(); }
+ });
+
+ it('keeps a finished recording available after a cancelled save and confines export to its chosen format', async () => {
+ const largeDisplay = { ...display, bounds: { x: 0, y: 0, width: 1280, height: 900 }, scaleFactor: 1 };
+ mocks.screen.getAllDisplays.mockReturnValue([largeDisplay]);
+ const overlay = pool.ensure(largeDisplay)!;
+ const owner = overlay.window.webContents;
+ pool.markShellReady(owner, owner.mainFrame);
+ const crop = { getSize: () => ({ width: 400, height: 300 }), toBitmap: () => Buffer.alloc(400 * 300 * 4), resize: () => crop };
+ const source = { getSize: () => ({ width: 1280, height: 900 }), toBitmap: () => Buffer.alloc(1280 * 900 * 4), crop: () => crop } as unknown as NativeImage;
+ const openRecording = vi.fn(() => false);
+ const session = new RegionScreenshotSession({ pool, captures: [{ display: largeDisplay, image: source }], helper: {} as SnapshotHelper, windows: [], lastRegions: new Map(), onClosed: vi.fn(), onResult: vi.fn(), openRecording });
+ await session.open();
+ session.painted(owner, owner.mainFrame, session.token);
+ session.startLive(owner, owner.mainFrame, session.token, 'video', { x: 0, y: 0, width: 400, height: 300 });
+ const clip = new Uint8Array(20); clip.set([0x1a, 0x45, 0xdf, 0xa3]);
+ // User-requested compact controls: dragging cannot cover source pixels;
+ // foreign requests and a failed preview handoff must retain this capture. tier: unit.
+ expect(session.updateRecordingControls(owner, {} as Electron.WebFrameMain, session.token, false, undefined, false)).toBeNull();
+ expect(session.updateRecordingControls(owner, owner.mainFrame, session.token, false, { x: NaN, y: 0 }, false)).toBeNull();
+ const moved = session.updateRecordingControls(owner, owner.mainFrame, session.token, false, { x: 0, y: 0 }, true)!;
+ expect(moved.x >= 400 || moved.y >= 300).toBe(true);
+ expect(windows[0].setIgnoreMouseEvents).toHaveBeenLastCalledWith(false, { forward: true });
+ session.updateRecordingControls(owner, owner.mainFrame, session.token, false, moved, false);
+ expect(windows[0].setIgnoreMouseEvents).toHaveBeenLastCalledWith(true, { forward: true });
+ expect(session.previewRecording(owner, owner.mainFrame, 'stale', clip, 'webm')).toBe(false);
+ expect(session.previewRecording(owner, owner.mainFrame, session.token, clip, 'gif')).toBe(false);
+ expect(session.previewRecording(owner, owner.mainFrame, session.token, clip, 'webm')).toBe(false);
+ expect(session.isClosed).toBe(false);
+ expect(await session.saveRecording(owner, owner.mainFrame, session.token, clip, 'gif')).toBe(false);
+ expect(mocks.saveRecording).not.toHaveBeenCalled();
+ mocks.saveRecording.mockResolvedValueOnce(false);
+ expect(await session.saveRecording(owner, owner.mainFrame, session.token, clip, 'webm')).toBe(false);
+ expect(session.isClosed).toBe(false);
+ expect(await session.saveRecording(owner, owner.mainFrame, session.token, clip, 'webm')).toBe(true);
+ openRecording.mockReturnValue(true);
+ expect(session.previewRecording(owner, owner.mainFrame, session.token, clip, 'webm')).toBe(true);
+ expect(session.isClosed).toBe(true);
+ expect(session.hasEditor).toBe(true);
+ });
+
+ // 用户反馈:录屏预览留在后台,下一段被旧预览占用。现有测试只检查可见性,
+ // 没有覆盖从不激活应用的采集面板交出焦点。最小输入:后台打开并收到 PAINTED。
+ // tier: unit;真实 RecordingPreview 入口,预热和非当前文档均不得抢焦点。
+ it.each(['darwin', 'win32'] as const)('activates clip preview only when presenting it on %s', (platform) => {
+ vi.stubGlobal('process', Object.create(process, { platform: { value: platform } }));
+ const preview = new RecordingPreview();
+ const clip = new Uint8Array(20); clip.set([0x1a, 0x45, 0xdf, 0xa3]);
+ preview.registerIpc(); preview.prewarm();
+ const win = windows[0], event = { sender: win.webContents, senderFrame: win.webContents.mainFrame };
+ const signal = (channel: string, ...args: unknown[]) => mocks.handlers.get(channel)!(event, ...args);
+ try {
+ signal(R.READY);
+ expect(preview.open(clip, 'webm', display)).toBe(true);
+ const doc = win.webContents.send.mock.calls.find(([name]) => name === R.BEGIN)![1];
+ signal(R.PAINTED, 'stale');
+ expect(mocks.focus).not.toHaveBeenCalled();
+ expect(win.focus).not.toHaveBeenCalled();
+ signal(R.PAINTED, doc.token);
+ expect(win.isVisible()).toBe(true);
+ expect(win.focus).toHaveBeenCalledOnce();
+ if (platform === 'darwin') {
+ expect(mocks.focus).toHaveBeenCalledExactlyOnceWith({ steal: true });
+ expect(mocks.focus.mock.invocationCallOrder[0]).toBeLessThan(win.focus.mock.invocationCallOrder[0]);
+ } else {
+ expect(mocks.focus).not.toHaveBeenCalled();
+ }
+ } finally { preview.dispose(); }
+ });
+
+ // New preview IPC/lifetime contract (Electron rules §3.1): existing image tests
+ // cannot cover clip save ownership, cancelled dialogs or replay after close.
+ // Minimal input: stale token after reopening; failed native save. tier: unit.
+ it('prewarms clip playback, validates its document owner and retains bytes after cancelling save', async () => {
+ const preview = new RecordingPreview();
+ const clip = new Uint8Array(20); clip.set([0x1a, 0x45, 0xdf, 0xa3]);
+ preview.registerIpc(); preview.prewarm();
+ const win = windows[0], event = { sender: win.webContents, senderFrame: win.webContents.mainFrame };
+ const signal = (channel: string, ...args: unknown[]) => mocks.handlers.get(channel)!(event, ...args);
+ try {
+ expect(win.isVisible()).toBe(false);
+ signal(R.READY);
+ expect(preview.open(clip, 'webm', display)).toBe(true);
+ const first = win.webContents.send.mock.calls.find(([name]) => name === R.BEGIN)![1];
+ expect(win.isVisible()).toBe(false);
+ mocks.handlers.get(R.PAINTED)!({ ...event, senderFrame: {} }, first.token);
+ expect(win.isVisible()).toBe(false);
+ signal(R.PAINTED, first.token);
+ expect(win.isVisible()).toBe(true);
+ expect(await mocks.handlers.get(R.SAVE)!({ ...event, sender: {} }, first.token)).toBe(false);
+ expect(await signal(R.SAVE, 'stale')).toBe(false);
+ expect(mocks.saveRecording).not.toHaveBeenCalled();
+ mocks.saveRecording.mockResolvedValueOnce(false);
+ expect(await signal(R.SAVE, first.token)).toBe(false);
+ expect(win.isVisible()).toBe(true);
+ expect(await signal(R.SAVE, first.token)).toBe(true);
+ expect(mocks.saveRecording).toHaveBeenLastCalledWith(clip, 'webm', expect.any(Function));
+ // Copy grants no path/payload input: only this preview's current document.
+ expect(await mocks.handlers.get(R.COPY)!({ ...event, sender: {} }, first.token)).toBe(false);
+ expect(await mocks.handlers.get(R.COPY)!({ ...event, senderFrame: {} }, first.token)).toBe(false);
+ expect(await signal(R.COPY, 'stale')).toBe(false);
+ expect(mocks.copyRecording).not.toHaveBeenCalled();
+ mocks.copyRecording.mockRejectedValueOnce(new Error('clipboard busy'));
+ expect(await signal(R.COPY, first.token)).toBe(false);
+ expect(win.isVisible()).toBe(true);
+ expect(await signal(R.COPY, first.token)).toBe(true);
+ expect(mocks.copyRecording).toHaveBeenLastCalledWith(clip, 'webm', expect.any(Function));
+ const stillCurrent = mocks.copyRecording.mock.calls.at(-1)![2] as () => boolean;
+ expect(stillCurrent()).toBe(true);
+ signal(R.CLOSE, first.token);
+ expect(stillCurrent()).toBe(false);
+ expect(win.isVisible()).toBe(false);
+ expect(win.webContents.send).toHaveBeenCalledWith(R.END);
+ expect(preview.open(clip, 'webm', display)).toBe(true);
+ const next = win.webContents.send.mock.calls.filter(([name]) => name === R.BEGIN).at(-1)![1];
+ signal(R.PAINTED, first.token);
+ expect(win.isVisible()).toBe(false);
+ signal(R.PAINTED, next.token);
+ expect(win.isVisible()).toBe(true);
+ expect(windows).toHaveLength(1);
+ } finally { preview.dispose(); }
+ });
+
+ // PR #7300 owner boundary: existing token checks cannot reject a prior account's
+ // clip. Unit: open after switching, then invalidate during save/copy; old pixels
+ // must disappear and deferred export must be cancelled, while the next owner works.
+ it.each([R.SAVE, R.COPY])('invalidates recording previews and pending %s on an owner boundary', async channel => {
+ const preview = new RecordingPreview();
+ const clip = new Uint8Array(20); clip.set([0x1a, 0x45, 0xdf, 0xa3]);
+ preview.registerIpc(); preview.prewarm();
+ const win = windows[0], event = { sender: win.webContents, senderFrame: win.webContents.mainFrame };
+ const signal = (name: string, ...args: unknown[]) => mocks.handlers.get(name)!(event, ...args);
+ try {
+ signal(R.READY);
+ expect(preview.open(clip, 'webm', display, 'old-owner')).toBe(false);
+ mocks.boundary = true;
+ expect(preview.open(clip, 'webm', display)).toBe(false);
+ mocks.boundary = false;
+ expect(preview.open(clip, 'webm', display)).toBe(true);
+ const doc = win.webContents.send.mock.calls.find(([name]) => name === R.BEGIN)![1];
+ signal(R.PAINTED, doc.token);
+ let finish!: () => void;
+ let isCurrent!: () => boolean;
+ const pending = new Promise<void>(resolve => { finish = resolve; });
+ if (channel === R.COPY) mocks.copyRecording.mockImplementationOnce(async (_bytes, _format, current) => {
+ isCurrent = current;
+ await pending;
+ if (!current()) throw new Error('cancelled');
+ });
+ else mocks.saveRecording.mockImplementationOnce(async (...args: unknown[]) => {
+ isCurrent = args[2] as () => boolean;
+ await pending;
+ return isCurrent();
+ });
+ const exported = signal(channel, doc.token);
+ expect(isCurrent()).toBe(true);
+ for (const invalidate of mocks.invalidations) invalidate();
+ mocks.ownerScope = 'owner-b:2';
+ expect(win.isDestroyed()).toBe(true);
+ expect(isCurrent()).toBe(false);
+ finish();
+ expect(await exported).toBe(false);
+ expect(await signal(channel, doc.token)).toBe(false);
+ expect(preview.open(clip, 'webm', display, 'owner-a:1')).toBe(false);
+ expect(preview.open(clip, 'webm', display)).toBe(true);
+ } finally { preview.dispose(); }
+ expect(mocks.invalidations.size).toBe(0);
+ });
+
+ // 用户反馈再次截图不可见; 现有覆盖没有验证用过的透明浮层与下一次会话隔离。
+ // 最小输入:上一轮导出后立即开启下一轮, 旧窗口随后销毁。tier: unit。
+ it('retires a used overlay so the next screenshot never re-shows it', async () => {
+ let active: RegionScreenshotSession;
+ pool.setGoneHandler((overlay) => { if (active?.owns(overlay)) active.close(); });
+ const run = async () => {
+ const overlay = pool.ensure(display)!;
+ const contents = overlay.window.webContents;
+ pool.markShellReady(contents, contents.mainFrame);
+ active = new RegionScreenshotSession({ pool, captures: [{ display, image }], helper: {} as SnapshotHelper, windows: [], lastRegions: new Map(), onClosed: vi.fn(), onResult: vi.fn() });
+ await active.open();
+ active.painted(contents, contents.mainFrame, active.token);
+ return windows.find((window) => window.webContents.id === contents.id)!;
+ };
+ const first = await run();
+ const contents = first.webContents as unknown as Electron.WebContents;
+ expect(active!.export(contents, contents.mainFrame, active!.token, {
+ action: 'copy', selection: { x: 0, y: 0, width: 2, height: 2 },
+ image: { width: 4, height: 4, data: new Uint8Array(64) },
+ })).toBe(true);
+ expect(first.isVisible()).toBe(false);
+ expect(first.isDestroyed()).toBe(false);
+ expect(pool.forContents(contents)).toBeNull();
+ const second = await run();
+ expect(second).not.toBe(first);
+ await vi.advanceTimersByTimeAsync(0);
+ expect(first.isDestroyed()).toBe(true);
+ expect(first.showInactive).toHaveBeenCalledTimes(1);
+ expect(active!.isClosed).toBe(false);
+ expect(second.isVisible()).toBe(true);
+ expect(pool.forContents(second.webContents as unknown as Electron.WebContents)?.window.webContents.id).toBe(second.webContents.id);
+ active!.close();
+ pool.destroyAll();
+ expect(second.isDestroyed()).toBe(true);
+ });
+
+ // Independent editor adds a new IPC owner and per-document readiness to the shared lifecycle.
+ // Minimal input: close, reopen, then deliver stale or foreign document signals. tier: unit.
+ // Frameless controls must minimize only their own current document (IPC ownership contract).
+ it('prewarms an editor, waits for each image, reuses its window and rejects stale or foreign exports', () => {
+ const result = vi.fn();
+ const editor = new ScreenshotEditor(result);
+ editor.registerIpc();
+ editor.prewarm();
+ const win = windows[0];
+ const event = { sender: win.webContents, senderFrame: win.webContents.mainFrame };
+ const bitmap = { width: 4, height: 80, data: new Uint8Array(1280) };
+ const selection = { x: 1, y: 2, width: 4, height: 8 };
+ const signal = (channel: string, ...args: unknown[]) => mocks.handlers.get(channel)!(event, ...args);
+ try {
+ expect(win.isVisible()).toBe(false);
+ signal(E.READY);
+ expect(editor.open(bitmap, display, selection)).toBe(true);
+ const first = win.webContents.send.mock.calls.find(([name]) => name === E.BEGIN)![1];
+ expect(win.isVisible()).toBe(false);
+ mocks.handlers.get(E.PAINTED)!({ ...event, senderFrame: {} }, first.token);
+ expect(win.isVisible()).toBe(false);
+ signal(E.PAINTED, first.token);
+ expect(win.isVisible()).toBe(true);
+ mocks.handlers.get(E.MINIMIZE)!({ ...event, sender: {} }, first.token);
+ mocks.handlers.get(E.MINIMIZE)!({ ...event, senderFrame: {} }, first.token);
+ signal(E.MINIMIZE, 'stale');
+ expect(win.minimize).not.toHaveBeenCalled();
+ signal(E.MINIMIZE, first.token);
+ expect(win.minimize).toHaveBeenCalledOnce();
+ expect(editor.open(bitmap, display, selection)).toBe(false);
+ signal(E.CANCEL, first.token);
+ expect(win.isVisible()).toBe(false);
+ expect(win.isDestroyed()).toBe(false);
+ expect(win.webContents.send).toHaveBeenCalledWith(E.END);
+ expect(editor.open(bitmap, display, selection)).toBe(true);
+ const second = win.webContents.send.mock.calls.filter(([name]) => name === E.BEGIN).at(-1)![1];
+ expect(second.token).not.toBe(first.token);
+ signal(E.PAINTED, first.token);
+ expect(win.isVisible()).toBe(false);
+ signal(E.PAINTED, second.token);
+ expect(win.isVisible()).toBe(true);
+ const payload = { action: 'copy', image: bitmap };
+ expect(signal(E.EXPORT, first.token, payload)).toBe(false);
+ expect(mocks.handlers.get(E.EXPORT)!({ ...event, sender: {} }, second.token, payload)).toBe(false);
+ expect(signal(E.EXPORT, second.token, { ...payload, image: { ...bitmap, height: 8 } })).toBe(false);
+ expect(signal(E.EXPORT, second.token, payload)).toBe(true);
+ expect(result).toHaveBeenCalledOnce();
+ expect(result.mock.calls[0][0].image.getSize()).toEqual({ width: 4, height: 80 });
+ expect(result.mock.calls[0][0].selection).toEqual(selection);
+ expect(windows).toHaveLength(1);
+ expect(win.isVisible()).toBe(false);
+ } finally { editor.dispose(); }
+ expect(win.isDestroyed()).toBe(true);
+ });
+
+ // A failed React tree must not remain cached forever; retry once, then permit a fresh user open.
+ it('recovers an editor rendering failure once and releases a document after repeated crashes', () => {
+ const editor = new ScreenshotEditor(vi.fn());
+ editor.registerIpc();
+ const bitmap = { width: 2, height: 2, data: new Uint8Array(16) };
+ const selection = { x: 0, y: 0, width: 2, height: 2 };
+ const ready = (win: ReturnType<typeof fakeWindow>) => {
+ const event = { sender: win.webContents, senderFrame: win.webContents.mainFrame };
+ mocks.handlers.get(E.READY)!(event);
+ const payload = win.webContents.send.mock.calls.find(([name]) => name === E.BEGIN)![1];
+ mocks.handlers.get(E.PAINTED)!(event, payload.token);
+ return event;
+ };
+ try {
+ expect(editor.open(bitmap, display, selection)).toBe(true);
+ const first = ready(windows[0]);
+ mocks.handlers.get(E.FAILED)!(first);
+ expect(windows[0].isDestroyed()).toBe(true);
+ expect(windows).toHaveLength(2);
+ ready(windows[1]);
+ expect(windows[1].isVisible()).toBe(true);
+ windows[1].webContents.emit('render-process-gone', {}, { reason: 'crashed' });
+ expect(windows[1].isDestroyed()).toBe(true);
+ expect(windows).toHaveLength(2);
+ expect(editor.open(bitmap, display, selection)).toBe(true);
+ ready(windows[2]);
+ expect(windows[2].isVisible()).toBe(true);
+ } finally { editor.dispose(); }
+ });
+
+ it('prewarms without showing or transforming the macOS Dock identity, and reuses the shell', () => {
+ pool.prewarm();
+ pool.prewarm();
+ expect(windows).toHaveLength(1);
+ expect(windows[0].showInactive).not.toHaveBeenCalled();
+ expect(windows[0].setVisibleOnAllWorkspaces).toHaveBeenCalledWith(
+ true,
+ expect.objectContaining({ skipTransformProcessType: true }),
+ );
+ });
+
+ it('closes an unresponsive overlay and bounds repeated failures', () => {
+ const gone = vi.fn();
+ pool.setGoneHandler(gone);
+ for (let i = 0; i < 4; i++) {
+ pool.ensure(display);
+ windows[i].emit('unresponsive');
+ expect(windows[i].isDestroyed()).toBe(true);
+ }
+ expect(gone).toHaveBeenCalledTimes(4);
+ expect(pool.ensure(display)).toBeNull();
+ });
+
+ it('accepts readiness only from the shell main frame and abandons unpainted screens', async () => {
+ const overlay = pool.ensure(display)!;
+ const contents = overlay.window.webContents;
+ pool.markShellReady(contents, {} as Electron.WebFrameMain);
+ expect(overlay.shellReady).toBe(false);
+ pool.markShellReady(contents, contents.mainFrame);
+ const closed = vi.fn();
+ const session = new RegionScreenshotSession({
+ pool,
+ captures: [{ display, image }],
+ helper: {} as SnapshotHelper,
+ windows: [],
+ lastRegions: new Map(),
+ onClosed: closed,
+ onResult: vi.fn(),
+ });
+ await session.open();
+ expect(windows[0].setOpacity).not.toHaveBeenCalledWith(1);
+ await vi.advanceTimersByTimeAsync(1500);
+ expect(session.isClosed).toBe(true);
+ expect(closed).toHaveBeenCalledTimes(1);
+ expect(windows[0].isVisible()).toBe(false);
+ });
+
+ // Startup regression (unit): on two displays, the first renderer may paint
+ // while the second shell is still loading. It must not reveal a frozen desktop
+ // before the native windows have their final bounds and visibility.
+ it('keeps both displays hidden until their startup geometry is established', async () => {
+ const second = { ...display, id: display.id + 1, bounds: { ...display.bounds, x: display.bounds.width } };
+ const firstOverlay = pool.ensure(display)!;
+ const secondOverlay = pool.ensure(second)!;
+ const first = firstOverlay.window.webContents;
+ const other = secondOverlay.window.webContents;
+ pool.markShellReady(first, first.mainFrame);
+ const session = new RegionScreenshotSession({ pool, captures: [{ display, image }, { display: second, image }], helper: {} as SnapshotHelper, windows: [], lastRegions: new Map(), onClosed: vi.fn(), onResult: vi.fn() });
+ for (const [index, owner] of [first, other].entries()) {
+ windows[index].webContents.send.mockImplementation((channel: string) => {
+ if (channel === 'region-screenshot:begin') session.painted(owner, owner.mainFrame, session.token);
+ });
+ }
+ const opening = session.open();
+ try {
+ await Promise.resolve();
+ expect(windows[0].setOpacity).not.toHaveBeenCalledWith(1);
+ pool.markShellReady(other, other.mainFrame);
+ await opening;
+ for (const [index, screen] of [display, second].entries()) {
+ expect(windows[index].setBounds).toHaveBeenLastCalledWith(screen.bounds, false);
+ expect(windows[index].setOpacity).toHaveBeenLastCalledWith(1);
+ }
+ } finally {
+ pool.markShellReady(other, other.mainFrame);
+ await opening;
+ session.close();
+ }
+ });
+
+ it('keeps screenshots on workArea changes but closes on scale changes', async () => {
+ const overlay = pool.ensure(display)!;
+ pool.markShellReady(overlay.window.webContents, overlay.window.webContents.mainFrame);
+ const session = new RegionScreenshotSession({
+ pool,
+ captures: [{ display, image }],
+ helper: {} as SnapshotHelper,
+ windows: [],
+ lastRegions: new Map(),
+ onClosed: vi.fn(),
+ onResult: vi.fn(),
+ });
+ await session.open();
+ const change = mocks.screen.on.mock.calls.find(
+ ([name]) => name === 'display-metrics-changed',
+ )![1];
+ change({}, display, ['workArea']);
+ expect(session.isClosed).toBe(false);
+ change({}, display, ['scaleFactor']);
+ expect(session.isClosed).toBe(true);
+ });
+
+ it('sends pin pixel dimensions matching an exported 2x screenshot and only displays after painting', async () => {
+ registerPinIpc();
+ const overlay = pool.ensure(display)!;
+ const contents = overlay.window.webContents;
+ pool.markShellReady(contents, contents.mainFrame);
+ const session = new RegionScreenshotSession({
+ pool,
+ captures: [{ display, image }],
+ helper: {} as SnapshotHelper,
+ windows: [],
+ lastRegions: new Map(),
+ onClosed: vi.fn(),
+ onResult: ({ image: result }) => openPin(result, { x: 0, y: 0, width: 2, height: 2 }),
+ });
+ await session.open();
+ expect(
+ session.export(contents, contents.mainFrame, session.token, {
+ action: 'pin',
+ selection: { x: 0, y: 0, width: 2, height: 2 },
+ image: { width: 4, height: 4, data: new Uint8Array(64) },
+ }),
+ ).toBe(true);
+ const window = windows[1];
+ const event = { sender: window.webContents, senderFrame: window.webContents.mainFrame };
+ mocks.handlers.get(P.SHELL_READY)!(event);
+ const init = window.webContents.send.mock.calls.find(([name]) => name === P.INIT)![1];
+ expect(init.image.width * init.image.height * 4).toBe(init.image.data.byteLength);
+ expect(window.isVisible()).toBe(false);
+ mocks.handlers.get(P.PAINTED)!(event);
+ expect(window.isVisible()).toBe(true);
+ });
+
+ // Unit: the editor retains the original selection, but a stitched bitmap must
+ // keep its aspect ratio and fit the monitor instead of using that selection's height.
+ it('pins a tall bitmap at its own aspect ratio without altering its pixels', () => {
+ const screenSpy = vi.spyOn(mocks.screen, 'getDisplayMatching').mockReturnValue({
+ workArea: { x: -800, y: 0, width: 800, height: 600 },
+ });
+ try {
+ registerPinIpc();
+ const pixels = Buffer.alloc(200 * 800 * 4);
+ openPin({ getSize: () => ({ width: 200, height: 800 }), toBitmap: () => pixels } as NativeImage,
+ { x: -200, y: 400, width: 200, height: 100 });
+ const window = windows.at(-1)!;
+ const event = { sender: window.webContents, senderFrame: window.webContents.mainFrame };
+ mocks.handlers.get(P.SHELL_READY)!(event);
+ const init = window.webContents.send.mock.calls.find(([name]) => name === P.INIT)![1];
+ expect({ width: init.image.width, height: init.image.height, bytes: init.image.data.byteLength })
+ .toEqual({ width: 200, height: 800, bytes: pixels.byteLength });
+ mocks.handlers.get(P.PAINTED)!(event);
+ expect(window.setBounds).toHaveBeenCalledWith({ x: -200, y: 0, width: 150, height: 600 }, false);
+ } finally { screenSpy.mockRestore(); }
+ });
+
+ it('destroys a pin that never paints instead of showing a black window', async () => {
+ openPin(image, { x: 0, y: 0, width: 2, height: 2 });
+ await vi.advanceTimersByTimeAsync(3000);
+ expect(windows[0].isDestroyed()).toBe(true);
+ expect(windows[0].showInactive).not.toHaveBeenCalled();
+ });
+
+ it('shares Escape without unregistering voice cancellation when a screenshot closes', () => {
+ const voice = vi.fn();
+ const releaseVoice = acquireOverlayEscape(voice)!;
+ const screenshot = vi.fn(() => releaseScreenshot());
+ const releaseScreenshot = acquireOverlayEscape(screenshot, 10)!;
+ const escape = mocks.register.mock.calls[0][1] as () => void;
+ escape();
+ expect(screenshot).toHaveBeenCalledTimes(1);
+ expect(voice).not.toHaveBeenCalled();
+ expect(mocks.unregister).not.toHaveBeenCalled();
+ escape();
+ expect(voice).toHaveBeenCalledTimes(1);
+ releaseVoice();
+ releaseScreenshot();
+ expect(mocks.unregister).toHaveBeenCalledExactlyOnceWith('Escape');
+ });
+
+ it('contains synchronous window creation failures during prewarm', () => {
+ mocks.create.mockImplementation(() => {
+ throw new Error('window unavailable');
+ });
+ expect(() => pool.prewarm()).not.toThrow();
+ expect(pool.ensure(display)).toBeNull();
+ });
+
+ it('forwards Escape to the focused editor without handing it to voice input', async () => {
+ const voice = vi.fn();
+ const releaseVoice = acquireOverlayEscape(voice)!;
+ const overlay = pool.ensure(display)!;
+ const contents = overlay.window.webContents;
+ pool.markShellReady(contents, contents.mainFrame);
+ const session = new RegionScreenshotSession({
+ pool,
+ captures: [{ display, image }],
+ helper: {} as SnapshotHelper,
+ windows: [],
+ lastRegions: new Map(),
+ onClosed: vi.fn(),
+ onResult: vi.fn(),
+ });
+ await session.open();
+ windows[0].isFocused.mockReturnValue(true);
+ session.focused(contents, contents.mainFrame, session.token);
+ const escape = mocks.register.mock.calls[0][1];
+ escape();
+ expect(windows[0].webContents.sendInputEvent).toHaveBeenCalledWith({
+ type: 'keyDown',
+ keyCode: 'Escape',
+ });
+ expect(session.isClosed).toBe(false);
+ expect(voice).not.toHaveBeenCalled();
+ session.close();
+ escape();
+ expect(voice).toHaveBeenCalledTimes(1);
+ releaseVoice();
+ });
+});
diff --git a/apps/desktop/src/main/region-screenshot/compose.ts b/apps/desktop/src/main/region-screenshot/compose.ts
new file mode 100644
index 0000000000..3a81c4efd9
--- /dev/null
+++ b/apps/desktop/src/main/region-screenshot/compose.ts
@@ -0,0 +1,84 @@
+import { ipcMain, type IpcMainInvokeEvent, type NativeImage } from 'electron';
+import { randomUUID } from 'node:crypto';
+import { activeOwnerScopeKey, getActiveDataOwnerPushStamp, isAppSessionBoundaryPending } from '../appSessionState';
+import { getDbClient } from '../localDb/client/current';
+
+import { ingestChatImageBuffer } from '../cindy-media/chatAttachments';
+import { focusMainWindow, getDeepLinkMainWindow, sendMainWindowMessage } from '../deepLink';
+import { createLogger } from '../logger';
+import {
+ REGION_SCREENSHOT_COMPOSE_CHANNEL,
+ type RegionScreenshotAiAction,
+ type RegionScreenshotComposeRequest,
+} from '../../shared/regionScreenshot';
+
+const log = createLogger('region-screenshot:compose');
+
+/**
+ * 截图交给新任务 (问 Cindy / 翻译 / 解释 / 提取文字)。
+ *
+ * main 只做两件事: 把图按粘贴图片同一条草稿入仓链路写入媒体仓 (blob + 账本行,
+ * 不挂引用, 用户发送时随消息挂引用), 然后唤醒主窗口。草稿写入、提示词与是否
+ * 自动发送都由主窗口 renderer 决定 (见 renderer/features/region-screenshot)。
+ * 只保留最新一条待处理请求; 主窗口还没加载好时由它挂载后自己来取。
+ */
+
+let pending: RegionScreenshotComposeRequest | null = null;
+let pendingExpiresAt = 0;
+let pendingOwnerScope: string | null = null;
+let requestGeneration = 0;
+const REQUEST_TTL_MS = 30_000;
+
+export async function handOffScreenshotToTask(
+ image: NativeImage,
+ action: RegionScreenshotAiAction,
+ ownerScope = activeOwnerScopeKey(),
+): Promise<void> {
+ if (isAppSessionBoundaryPending() || ownerScope !== activeOwnerScopeKey()) return;
+ const ownerStamp = getActiveDataOwnerPushStamp();
+ const db = getDbClient().drizzle;
+ const generation = ++requestGeneration;
+ const expiresAt = Date.now() + REQUEST_TTL_MS;
+ pending = null;
+ const png = image.toPNG();
+ const { url, filename } = await ingestChatImageBuffer({ buffer: png, mimeType: 'image/png' }, db);
+ if (generation !== requestGeneration || Date.now() >= expiresAt
+ || isAppSessionBoundaryPending() || ownerScope !== activeOwnerScopeKey()) return;
+ const size = image.getSize();
+ pending = {
+ id: randomUUID(),
+ ownerStamp,
+ action,
+ url,
+ filename,
+ bytes: png.byteLength,
+ width: size.width,
+ height: size.height,
+ };
+ pendingExpiresAt = expiresAt;
+ pendingOwnerScope = ownerScope;
+ log.info('screenshot handed to task', { action });
+ focusMainWindow();
+ sendMainWindowMessage(REGION_SCREENSHOT_COMPOSE_CHANNEL.WAKE, null);
+}
+
+function isMainWindowEvent(event: IpcMainInvokeEvent): boolean {
+ const main = getDeepLinkMainWindow();
+ return (
+ !!main &&
+ !main.isDestroyed() &&
+ event.sender === main.webContents &&
+ !!event.senderFrame &&
+ event.senderFrame === event.sender.mainFrame
+ );
+}
+
+export function registerScreenshotComposeIpc(): void {
+ ipcMain.handle(REGION_SCREENSHOT_COMPOSE_CHANNEL.TAKE, (event) => {
+ if (!isMainWindowEvent(event)) return null;
+ const request = Date.now() < pendingExpiresAt && !isAppSessionBoundaryPending()
+ && pendingOwnerScope === activeOwnerScopeKey() ? pending : null;
+ pending = null;
+ return request;
+ });
+}
diff --git a/apps/desktop/src/main/region-screenshot/editor.ts b/apps/desktop/src/main/region-screenshot/editor.ts
new file mode 100644
index 0000000000..a43f0a6d0b
--- /dev/null
+++ b/apps/desktop/src/main/region-screenshot/editor.ts
@@ -0,0 +1,127 @@
+import { app, ipcMain, nativeImage, nativeTheme, screen, type BrowserWindow, type Display, type IpcMainEvent, type IpcMainInvokeEvent } from 'electron';
+import { randomUUID } from 'node:crypto';
+import { activeOwnerScopeKey } from '../appSessionState';
+import path from 'node:path';
+import { ResourceUsageWindowController } from '../resource-usage-window/controller';
+import { getResolvedMainLocale, t } from '../i18n';
+import { createScreenshotPageWindow } from './pageWindow';
+import { REGION_SCREENSHOT_EDITOR_CHANNEL as C, isRegionScreenshotAction, validateRegionBitmap, type RegionRect, type RegionScreenshotBitmap, type RegionScreenshotBegin } from '../../shared/regionScreenshot';
+import type { RegionScreenshotResult } from './session';
+
+interface EditorDocument {
+ ownerScope: string;
+ payload: RegionScreenshotBegin;
+ display: Display;
+ selection: RegionRect;
+}
+
+/** Ordinary auxiliary window: hidden prewarm/reuse and bounded recovery use the shared controller. */
+export class ScreenshotEditor {
+ private window: BrowserWindow | null = null;
+ private ready = false;
+ private document: EditorDocument | null = null;
+ private readonly controller: ResourceUsageWindowController;
+
+ constructor(private readonly onResult: (result: RegionScreenshotResult) => void) {
+ this.controller = new ResourceUsageWindowController({
+ createWindow: () => {
+ this.ready = false;
+ const window = createScreenshotPageWindow({
+ width: 1000, height: 800, minWidth: 760, minHeight: 420,
+ frame: false, roundedCorners: true, resizable: true,
+ minimizable: true, maximizable: true, fullscreenable: true, skipTaskbar: false,
+ icon: app.isPackaged ? path.join(process.resourcesPath, 'icon.png') : path.join(__dirname, '../../resources/icon.png'),
+ backgroundColor: nativeTheme.shouldUseDarkColors ? '#1f1f1e' : '#f8f8f6',
+ preload: 'regionScreenshotEditorPreload.js', query: 'regionScreenshotEditor',
+ });
+ this.window = window;
+ window.on('closed', () => { if (this.window === window) { this.window = null; this.ready = false; } });
+ return window;
+ },
+ prewarmWork: false,
+ // Minimizing or switching a macOS Space must retain the current image and annotations.
+ pauseWhenHidden: false,
+ activityChannel: C.ACTIVITY,
+ isOpenSender: (sender) => sender === this.window?.webContents,
+ resolveNativeTitle: () => t('regionScreenshot.live.edit'),
+ onCloseRequested: () => this.close(),
+ onUnavailable: () => { this.document = null; },
+ });
+ }
+
+ prewarm(): void { this.controller.prewarm(); }
+ dispose(): void { this.document = null; this.controller.dispose(); }
+
+ open(image: RegionScreenshotBitmap, display: Display, selection: RegionRect, ownerScope = activeOwnerScopeKey()): boolean {
+ // Do not overwrite an unfinished image if another capture reaches Edit.
+ if (this.document) return false;
+ this.controller.prewarm();
+ const window = this.window;
+ if (!window || window.isDestroyed()) return false;
+ this.document = { display, selection, ownerScope, payload: {
+ token: randomUUID(), locale: getResolvedMainLocale(),
+ viewport: { width: image.width, height: image.height }, scaleFactor: 1,
+ frame: image, windows: [], lastRegion: selection, cursor: null,
+ safeArea: { x: 0, y: 0, width: image.width, height: image.height },
+ } };
+ const area = screen.getDisplayMatching(display.bounds).workArea;
+ const width = Math.min(1000, area.width), height = Math.min(800, area.height);
+ if (!window.isMaximized() && !window.isFullScreen()) window.setBounds({
+ x: Math.round(area.x + (area.width - width) / 2), y: Math.round(area.y + (area.height - height) / 2), width, height,
+ });
+ this.controller.resetPresentation();
+ if (this.ready) window.webContents.send(C.BEGIN, this.document.payload);
+ if (this.controller.open(window.webContents)) return true;
+ this.document = null;
+ return false;
+ }
+
+ private owns(event: IpcMainEvent | IpcMainInvokeEvent, token?: unknown): boolean {
+ return !!this.window && !this.window.isDestroyed() && event.sender === this.window.webContents
+ && event.senderFrame === event.sender.mainFrame
+ && (token === undefined || token === this.document?.payload.token);
+ }
+
+ private close(): void {
+ const window = this.window;
+ this.document = null;
+ if (!window || window.isDestroyed()) return;
+ window.webContents.send(C.END);
+ this.controller.close(window.webContents);
+ this.controller.resetPresentation();
+ }
+
+ registerIpc(): void {
+ ipcMain.on(C.MINIMIZE, (event, token: unknown) => {
+ if (this.document && typeof token === 'string' && this.owns(event, token)) this.window?.minimize();
+ });
+ ipcMain.on(C.FAILED, (event) => {
+ if (this.owns(event)) this.controller.rendererFailed(event.sender);
+ });
+ ipcMain.on(C.READY, (event) => {
+ if (!this.owns(event)) return;
+ this.ready = true;
+ this.controller.markRendererReady(event.sender);
+ if (this.document) event.sender.send(C.BEGIN, this.document.payload);
+ });
+ ipcMain.on(C.PAINTED, (event, token: unknown) => {
+ if (this.document && this.owns(event, token)) this.controller.markPresentationReady(event.sender);
+ });
+ ipcMain.on(C.CANCEL, (event, token: unknown) => {
+ if (this.document && typeof token === 'string' && this.owns(event, token)) this.close();
+ });
+ ipcMain.handle(C.EXPORT, (event, token: unknown, raw: unknown) => {
+ const doc = this.document;
+ if (!doc || typeof token !== 'string' || !this.owns(event, token) || !raw || typeof raw !== 'object') return false;
+ const { action, image: rawImage } = raw as Record<string, unknown>;
+ if (!isRegionScreenshotAction(action)) return false;
+ const bitmap = validateRegionBitmap(rawImage, doc.payload.frame);
+ if (!bitmap || bitmap.width !== doc.payload.frame.width || bitmap.height !== doc.payload.frame.height) return false;
+ const image = nativeImage.createFromBitmap(Buffer.from(bitmap.data.buffer, bitmap.data.byteOffset, bitmap.data.byteLength), { width: bitmap.width, height: bitmap.height, scaleFactor: 1 });
+ if (image.isEmpty()) return false;
+ this.close();
+ this.onResult({ action, image, display: doc.display, selection: doc.selection, ownerScope: doc.ownerScope });
+ return true;
+ });
+ }
+}
diff --git a/apps/desktop/src/main/region-screenshot/index.ts b/apps/desktop/src/main/region-screenshot/index.ts
new file mode 100644
index 0000000000..dd6c90156f
--- /dev/null
+++ b/apps/desktop/src/main/region-screenshot/index.ts
@@ -0,0 +1,382 @@
+import {
+ app,
+ clipboard,
+ desktopCapturer,
+ dialog,
+ globalShortcut,
+ ipcMain,
+ screen,
+ shell,
+ systemPreferences,
+ type Display,
+} from 'electron';
+
+import { createLogger } from '../logger';
+import { activeOwnerScopeKey, isAppSessionBoundaryPending } from '../appSessionState';
+import { t } from '../i18n';
+import {
+ getAppShortcutStore,
+ setGlobalShortcutRegistrationFailures,
+ subscribeAppShortcutRecording,
+} from '../app-shortcuts';
+import { enumerateDesktopSources } from '../remote-desktop/captureSource';
+import { MAC_SCREEN_RECORDING_SETTINGS_URL } from '../computer-permission-guide/request';
+import { comboToElectronAccelerator } from '../../shared/appShortcuts';
+import {
+ isRegionScreenshotAiAction,
+ REGION_SCREENSHOT_CHANNEL as C,
+ type RegionRect,
+ type RegionScreenshotAction,
+} from '../../shared/regionScreenshot';
+import { handOffScreenshotToTask, registerScreenshotComposeIpc } from './compose';
+import { OverlayPool } from './overlays';
+import { ScreenshotEditor } from './editor';
+import { RecordingPreview } from './recordingPreview';
+import { closeAllPins, openPin, registerPinIpc } from './pins';
+import { saveScreenshotImage } from './save';
+import {
+ RegionScreenshotSession,
+ type DisplayCapture,
+ type RegionScreenshotResult,
+} from './session';
+import { resolveSnapshotBinary, SnapshotHelper, type SnapshotWindow } from './snapshotHost';
+import { REGION_CAPTURE_CHANNEL as LIVE } from '../../shared/regionCapture';
+
+/**
+ * 全局框选截图: 用户在「键盘快捷键」里可改的 region-screenshot 快捷键 →
+ * 定格所有显示器 (同时拍下窗口列表) → 每块屏一个预热好的框选浮层 → 选区、标注后
+ * 复制 / 保存 / 贴图, 或交给 Cindy 新任务 (问 / 翻译 / 解释 / 提取文字)。
+ *
+ * 只在 macOS / Windows 启用 (registry 的 platforms 决定)。快捷键在设置页录制
+ * 期间暂时注销, 让录制能收到当前组合; 注册失败 (多为被其它应用占用) 上报给
+ * app-shortcuts, 设置页在该行提示。
+ */
+
+const log = createLogger('region-screenshot');
+const SHORTCUT_ID = 'region-screenshot' as const;
+const CAPTURE_TIMEOUT_MS = 5000;
+/** 主窗口首帧稳定后再在后台预热浮层, 不和启动抢资源。 */
+const PREWARM_DELAY_MS = 8000;
+const DISPLAY_SETTLE_MS = 1500;
+/** 截图结束后为下一次建好新浮层; 稍等片刻, 不和复制 / 贴图等后续动作抢资源。 */
+const REPREWARM_DELAY_MS = 1000;
+
+let initialized = false;
+let registeredAccelerator: string | null = null;
+let recording = false;
+let starting = false;
+let active: RegionScreenshotSession | null = null;
+let prewarmTimer: ReturnType<typeof setTimeout> | null = null;
+const pool = new OverlayPool();
+const recordingPreview = new RecordingPreview();
+const editor = new ScreenshotEditor((result) => {
+ lastRegions.set(result.display.id, result.selection);
+ void runAction(result);
+});
+/** 每块显示器上一次截图的选区 (DIP), 供「重复上次区域」; 只在本次运行内记住。 */
+const lastRegions = new Map<number, RegionRect>();
+const disposers: Array<() => void> = [];
+
+export function initRegionScreenshot(): void {
+ if (initialized) return;
+ initialized = true;
+ registerIpc();
+ editor.registerIpc();
+ recordingPreview.registerIpc();
+ registerPinIpc();
+ registerScreenshotComposeIpc();
+ pool.setGoneHandler((overlay) => {
+ if (active?.owns(overlay)) active.close();
+ });
+ disposers.push(getAppShortcutStore().subscribe(syncShortcut));
+ disposers.push(
+ subscribeAppShortcutRecording((isRecording) => {
+ recording = isRecording;
+ syncShortcut();
+ }),
+ );
+ const onDisplaysChanged = () => {
+ if (active) return;
+ pool.reset();
+ schedulePrewarm(DISPLAY_SETTLE_MS);
+ };
+ screen.on('display-added', onDisplaysChanged);
+ screen.on('display-removed', onDisplaysChanged);
+ const onMetricsChanged = (_event: Electron.Event, _display: Display, metrics: string[]) => {
+ if (metrics.some((metric) => ['bounds', 'scaleFactor', 'rotation'].includes(metric))) onDisplaysChanged();
+ };
+ screen.on('display-metrics-changed', onMetricsChanged);
+ disposers.push(() => {
+ screen.removeListener('display-added', onDisplaysChanged);
+ screen.removeListener('display-removed', onDisplaysChanged);
+ screen.removeListener('display-metrics-changed', onMetricsChanged);
+ });
+ syncShortcut();
+}
+
+export function stopRegionScreenshot(): void {
+ for (const dispose of disposers.splice(0)) dispose();
+ if (registeredAccelerator) globalShortcut.unregister(registeredAccelerator);
+ registeredAccelerator = null;
+ active?.close();
+ // 会话结束会排一次预热,必须在它之后清掉。
+ if (prewarmTimer) clearTimeout(prewarmTimer);
+ pool.destroyAll();
+ editor.dispose();
+ recordingPreview.dispose();
+ closeAllPins();
+}
+
+function schedulePrewarm(delay: number): void {
+ if (prewarmTimer) clearTimeout(prewarmTimer);
+ prewarmTimer = setTimeout(() => {
+ prewarmTimer = null;
+ if (!registeredAccelerator || active) return;
+ pool.prewarm();
+ editor.prewarm();
+ recordingPreview.prewarm();
+ // 源码模式顺带把识别程序编译好, 第一次截图不用等编译。
+ void resolveSnapshotBinary();
+ }, delay);
+}
+
+function desiredAccelerator(): string | null {
+ const combo = getAppShortcutStore().getEffectiveCombos(SHORTCUT_ID)[0];
+ return combo ? comboToElectronAccelerator(combo, process.platform) : null;
+}
+
+function syncShortcut(): void {
+ if (!initialized) return;
+ const desired = recording ? null : desiredAccelerator();
+ if (desired === registeredAccelerator) return;
+ if (registeredAccelerator) globalShortcut.unregister(registeredAccelerator);
+ registeredAccelerator = null;
+ // 录制期间只是暂时让出按键, 不改变「是否被占用」的提示。
+ if (recording) return;
+ if (!desired) {
+ setGlobalShortcutRegistrationFailures([]);
+ return;
+ }
+ let ok = false;
+ try {
+ ok = globalShortcut.register(desired, () => {
+ void startRegionScreenshot();
+ });
+ } catch (error) {
+ log.warn('screenshot shortcut registration threw', { accelerator: desired, error });
+ }
+ if (ok) {
+ registeredAccelerator = desired;
+ setGlobalShortcutRegistrationFailures([]);
+ schedulePrewarm(PREWARM_DELAY_MS);
+ } else {
+ log.warn('screenshot shortcut is unavailable', { accelerator: desired });
+ setGlobalShortcutRegistrationFailures([SHORTCUT_ID]);
+ }
+}
+
+function registerIpc(): void {
+ ipcMain.handle(LIVE.CONTROLS, (event, token: unknown, expanded: unknown, point: unknown, dragging: unknown) => active?.updateRecordingControls(event.sender, event.senderFrame, token, expanded, point, dragging) ?? null);
+ ipcMain.handle(LIVE.PREVIEW, (event, token: unknown, bytes: unknown, format: unknown) => active?.previewRecording(event.sender, event.senderFrame, token, bytes, format) ?? false);
+ ipcMain.handle(LIVE.AUTO_SCROLL, (event, token: unknown, enabled: unknown) => active?.autoScroll(event.sender, event.senderFrame, token, enabled) ?? false);
+ ipcMain.handle(LIVE.START, (event, token: unknown, mode: unknown, selection: unknown) => active?.startLive(event.sender, event.senderFrame, token, mode, selection) ?? null);
+ ipcMain.handle(LIVE.FRAME, (event, token: unknown, keys: unknown, previewHeight: unknown) => active?.liveFrame(event.sender, event.senderFrame, token, keys, previewHeight) ?? null);
+ ipcMain.handle(LIVE.SAVE, (event, token: unknown, bytes: unknown, format: unknown) => active?.saveRecording(event.sender, event.senderFrame, token, bytes, format) ?? false);
+ ipcMain.handle(LIVE.EDIT, (event, token: unknown, image: unknown) => active?.restoreEditor(event.sender, event.senderFrame, token, image) ?? false);
+ ipcMain.handle(LIVE.HOLD, (event, token: unknown) => active?.holdCapture(event.sender, event.senderFrame, token));
+ // 所有通道都按 sender 反查浮层, 再由当前会话核对 token; 无会话或来源不符一律忽略。
+ ipcMain.on(C.SHELL_READY, (event) => pool.markShellReady(event.sender, event.senderFrame));
+ ipcMain.on(C.PAINTED, (event, token: unknown) =>
+ active?.painted(event.sender, event.senderFrame, token),
+ );
+ ipcMain.on(C.FOCUSED, (event, token: unknown) =>
+ active?.focused(event.sender, event.senderFrame, token),
+ );
+ ipcMain.on(C.SELECTION_START, (event, token: unknown) =>
+ active?.selectionStarted(event.sender, event.senderFrame, token),
+ );
+ ipcMain.on(C.COPY_TEXT, (event, token: unknown, text: unknown) =>
+ active?.copyText(event.sender, event.senderFrame, token, text),
+ );
+ ipcMain.on(C.CANCEL, (event, token: unknown) =>
+ active?.cancel(event.sender, event.senderFrame, token),
+ );
+ ipcMain.on(C.ABANDON, (event) => {
+ const overlay = pool.forContents(event.sender);
+ if (!overlay || !active?.owns(overlay) || event.senderFrame !== event.sender.mainFrame) return;
+ active.abandon(event.sender, event.senderFrame);
+ pool.discard(overlay);
+ });
+ ipcMain.handle(
+ C.ELEMENTS_AT,
+ (event, token: unknown, windowId: unknown, x: unknown, y: unknown) =>
+ active?.elementsAt(event.sender, event.senderFrame, token, windowId, x, y) ?? [],
+ );
+ ipcMain.handle(
+ C.EXPORT,
+ (event, token: unknown, payload: unknown) =>
+ active?.export(event.sender, event.senderFrame, token, payload) ?? false,
+ );
+}
+
+async function startRegionScreenshot(): Promise<void> {
+ if (isAppSessionBoundaryPending()) return;
+ const ownerScope = activeOwnerScopeKey();
+ if (active || starting) return;
+ if (pool.isDisabled) {
+ void dialog.showMessageBox({ type: 'warning', message: t('regionScreenshot.captureFailed'), noLink: true });
+ return;
+ }
+ starting = true;
+ const startedAt = Date.now();
+ let helper: SnapshotHelper | null = null;
+ let abandoned = false;
+ try {
+ if (process.platform === 'darwin' && !(await ensureMacScreenRecordingPermission())) return;
+ // 首次开发编译不阻塞截图,本次降级为手动框选;不拿迟到的窗口列表匹配旧定格画面。
+ const helperReady = SnapshotHelper.start(false).then((value) => {
+ if (abandoned) value.dispose();
+ else helper = value;
+ return value;
+ });
+ const snapshot = helperReady.then(async (h) => ({
+ windows: await h.windows(),
+ frontmostPid: await h.frontmostPid(),
+ topInsets: await h.screenInsets(),
+ }));
+ const [captures, snap] = await Promise.all([
+ captureDisplays(screen.getAllDisplays()),
+ snapshot.catch(() => ({ windows: [] as SnapshotWindow[], frontmostPid: null, topInsets: new Map<number, number>() })),
+ ]);
+ helper = await helperReady;
+ if (isAppSessionBoundaryPending() || ownerScope !== activeOwnerScopeKey()) return;
+ const capturedAt = Date.now();
+ if (captures.length === 0) {
+ log.warn('no display could be captured');
+ void dialog.showMessageBox({ type: 'warning', message: t('regionScreenshot.captureFailed'), noLink: true });
+ return;
+ }
+ const sessionHelper = helper;
+ let result: RegionScreenshotResult | null = null;
+ const session = new RegionScreenshotSession({
+ pool,
+ captures,
+ helper: sessionHelper,
+ windows: snap.windows,
+ topInsets: snap.topInsets,
+ lastRegions,
+ openEditor: (image, display, selection) => editor.open(image, display, selection, ownerScope),
+ openRecording: (bytes, format, display) => recordingPreview.open(bytes, format, display, ownerScope),
+ onResult: (value) => {
+ result = value;
+ lastRegions.set(value.display.id, value.selection);
+ void runAction({ ...value, ownerScope });
+ },
+ onClosed: () => {
+ if (active === session) active = null;
+ schedulePrewarm(REPREWARM_DELAY_MS);
+ // export() 先结束会话再回传结果, 等这一轮同步代码走完再决定焦点去向。
+ queueMicrotask(() => {
+ const action = (result as RegionScreenshotResult | null)?.action ?? null;
+ if (snap.frontmostPid !== null && !session.hasEditor && !takesFocus(action)) {
+ void sessionHelper.activate(snap.frontmostPid).finally(() => sessionHelper.dispose());
+ } else {
+ sessionHelper.dispose();
+ }
+ });
+ },
+ });
+ active = session;
+ helper = null;
+ const opened = await session.open();
+ log.info('screenshot opened', {
+ opened,
+ captureMs: capturedAt - startedAt,
+ openMs: Date.now() - capturedAt,
+ windows: snap.windows.length,
+ });
+ } catch (error) {
+ log.warn('region screenshot failed', { error });
+ active?.close();
+ } finally {
+ abandoned = true;
+ helper?.dispose();
+ starting = false;
+ }
+}
+
+/** 这些动作之后焦点本该留在 Cindy (主窗口 / 保存框), 不还给截图前的应用。 */
+function takesFocus(action: RegionScreenshotAction | null): boolean {
+ return action === 'save' || isRegionScreenshotAiAction(action);
+}
+
+async function runAction({ action, image, display, selection, ownerScope }: RegionScreenshotResult) {
+ try {
+ if (action === 'copy') {
+ clipboard.writeImage(image);
+ } else if (action === 'save') {
+ await saveScreenshotImage(image);
+ } else if (action === 'pin') {
+ openPin(image, {
+ x: Math.round(display.bounds.x + selection.x),
+ y: Math.round(display.bounds.y + selection.y),
+ width: Math.max(1, Math.round(selection.width)),
+ height: Math.max(1, Math.round(selection.height)),
+ }, ownerScope);
+ } else {
+ await handOffScreenshotToTask(image, action, ownerScope);
+ }
+ } catch (error) {
+ log.warn('screenshot action failed', { action, error });
+ }
+}
+
+/**
+ * Electron 在 macOS 上只区分已授权 / 未授权。未授权时先枚举一次屏幕源, 让
+ * Cindy 出现在系统的屏幕录制列表里 (首次还会弹出系统询问), 再说明去哪里开启。
+ */
+async function ensureMacScreenRecordingPermission(): Promise<boolean> {
+ if (systemPreferences.getMediaAccessStatus('screen') === 'granted') return true;
+ await enumerateDesktopSources(
+ () => desktopCapturer.getSources({ types: ['screen'], thumbnailSize: { width: 0, height: 0 } }),
+ CAPTURE_TIMEOUT_MS,
+ ).catch(() => undefined);
+ if (systemPreferences.getMediaAccessStatus('screen') === 'granted') return true;
+ app.focus({ steal: true });
+ const { response } = await dialog.showMessageBox({
+ type: 'info',
+ message: t('regionScreenshot.permission.title'),
+ detail: t('regionScreenshot.permission.detail'),
+ buttons: [t('regionScreenshot.permission.openSettings'), t('regionScreenshot.permission.later')],
+ defaultId: 0,
+ cancelId: 1,
+ noLink: true,
+ });
+ if (response === 0) await shell.openExternal(MAC_SCREEN_RECORDING_SETTINGS_URL);
+ return false;
+}
+
+/**
+ * 定格每块显示器。所有屏共用一个缩略图尺寸上限 (取各屏物理像素的最大值),
+ * 再按 display_id 精确对应, 不按顺序猜测; 只有单屏单源时才直接对应。
+ */
+async function captureDisplays(displays: readonly Display[]): Promise<DisplayCapture[]> {
+ const width = Math.max(...displays.map((d) => Math.round(d.bounds.width * d.scaleFactor)));
+ const height = Math.max(...displays.map((d) => Math.round(d.bounds.height * d.scaleFactor)));
+ const sources = await enumerateDesktopSources(
+ () => desktopCapturer.getSources({ types: ['screen'], thumbnailSize: { width, height } }),
+ CAPTURE_TIMEOUT_MS,
+ );
+ const captures: DisplayCapture[] = [];
+ for (const display of displays) {
+ const source =
+ sources.find((s) => s.display_id === String(display.id)) ??
+ (displays.length === 1 && sources.length === 1 ? sources[0] : undefined);
+ if (!source || source.thumbnail.isEmpty()) {
+ log.warn('display capture missing', { displayId: display.id });
+ continue;
+ }
+ captures.push({ display, image: source.thumbnail });
+ }
+ return captures;
+}
diff --git a/apps/desktop/src/main/region-screenshot/liveCapture.ts b/apps/desktop/src/main/region-screenshot/liveCapture.ts
new file mode 100644
index 0000000000..661a370fcf
--- /dev/null
+++ b/apps/desktop/src/main/region-screenshot/liveCapture.ts
@@ -0,0 +1,62 @@
+import { desktopCapturer, nativeImage, screen, type Display } from 'electron';
+import type { SnapshotHelper } from './snapshotHost';
+import { NativeDesktopCapture } from '../remote-desktop/nativeCapture';
+import { regionSelectionToImageCrop, type RegionRect, type RegionScreenshotBitmap } from '../../shared/regionScreenshot';
+import type { RegionCaptureMode } from '../../shared/regionCapture';
+import { enumerateDesktopSources } from '../remote-desktop/captureSource';
+
+/** Main crops before crossing IPC. No whole-display pixels reach the live panel. */
+export async function captureLiveRegion(display: Display, selection: RegionRect, mode: RegionCaptureMode, helper?: SnapshotHelper): Promise<RegionScreenshotBitmap> {
+ if (process.platform === 'win32' && helper) {
+ const rect = screen.dipToScreenRect(null, { ...selection, x: selection.x + display.bounds.x, y: selection.y + display.bounds.y });
+ const image = await helper.capture(rect, mode === 'scroll' ? 32768 : mode === 'gif' ? 960 : 1920);
+ if (image) return image;
+ // The optional helper may have exited after an accessibility query timed out.
+ // Keep capture usable through the bounded, user-session Electron path below.
+ }
+ const sources = await enumerateDesktopSources(() => desktopCapturer.getSources({
+ types: ['screen'],
+ thumbnailSize: { width: Math.round(display.bounds.width * display.scaleFactor), height: Math.round(display.bounds.height * display.scaleFactor) },
+ }), 5000);
+ const source = sources.find((candidate) => candidate.display_id === String(display.id));
+ if (!source || source.thumbnail.isEmpty()) throw new Error('Display capture unavailable');
+ const mapping = regionSelectionToImageCrop(selection, display.bounds, source.thumbnail.getSize(), display.scaleFactor);
+ if (!mapping) throw new Error('Invalid capture region');
+ let image = source.thumbnail.crop(mapping.crop).resize(mapping.output);
+ const maxSide = mode === 'gif' ? 960 : mode === 'video' ? 1920 : 32768;
+ const ratio = Math.min(1, maxSide / Math.max(mapping.output.width, mapping.output.height));
+ if (ratio < 1) image = image.resize({ width: Math.max(1, Math.round(mapping.output.width * ratio)), height: Math.max(1, Math.round(mapping.output.height * ratio)) });
+ const size = image.getSize();
+ return { ...size, data: new Uint8Array(image.toBitmap()) };
+}
+
+/** Reuses one user-session capture backend for the recording; never opens the
+ * Windows elevated remote-desktop broker or grants a renderer screen access. */
+export class RegionVideoCapture {
+ private native: NativeDesktopCapture | null = null;
+ private generation = 0;
+ constructor(private readonly helper: SnapshotHelper) {}
+
+ async frame(display: Display, selection: RegionRect, mode: 'video' | 'gif'): Promise<RegionScreenshotBitmap> {
+ const edge = mode === 'gif' ? 960 : 1920;
+ const generation = this.generation;
+ if (process.platform === 'win32') {
+ const result = await captureLiveRegion(display, selection, mode, this.helper);
+ if (generation !== this.generation) throw new Error('Region capture unavailable');
+ return result;
+ }
+ if (!this.native) {
+ this.native = new NativeDesktopCapture();
+ }
+ const frame = await this.native.frame(String(display.id), true, { quality: 'hd', fps: 30, audio: false });
+ if (generation !== this.generation || !frame || typeof frame === 'string') throw new Error('Region capture unavailable');
+ const source = nativeImage.createFromBuffer(Buffer.from(frame.jpeg, 'base64'));
+ const mapping = regionSelectionToImageCrop(selection, display.bounds, source.getSize(), display.scaleFactor);
+ if (!mapping) throw new Error('Invalid capture region');
+ const ratio = Math.min(1, edge / Math.max(mapping.output.width, mapping.output.height));
+ const image = source.crop(mapping.crop).resize({ width: Math.max(1, Math.round(mapping.output.width * ratio)), height: Math.max(1, Math.round(mapping.output.height * ratio)) });
+ return { ...image.getSize(), data: new Uint8Array(image.toBitmap()) };
+ }
+
+ stop(): void { this.generation++; this.native?.stop(); this.native = null; }
+}
diff --git a/apps/desktop/src/main/region-screenshot/overlays.ts b/apps/desktop/src/main/region-screenshot/overlays.ts
new file mode 100644
index 0000000000..6f84cb6e3e
--- /dev/null
+++ b/apps/desktop/src/main/region-screenshot/overlays.ts
@@ -0,0 +1,249 @@
+import { app, screen, type BrowserWindow, type Display, type WebContents } from 'electron';
+
+import { createLogger } from '../logger';
+import { createScreenshotPageWindow } from './pageWindow';
+
+const log = createLogger('region-screenshot:overlays');
+
+/** 隐藏预热的浮层迟迟没挂载时放弃这块屏, 不让按下快捷键后一直没反应。 */
+const SHELL_TIMEOUT_MS = 4000;
+/** 浮层 renderer 崩溃后的重建额度: 10 分钟内最多 3 次, 超出后本次运行不再截图。 */
+const CRASH_LIMIT = 3;
+const CRASH_WINDOW_MS = 10 * 60_000;
+
+/** Chromium Aura 的显示动画会缩放整个截图,DWM / thickFrame 开关无法禁用它。 */
+export function showScreenshotOverlay(window: BrowserWindow): void {
+ withoutScreenshotAnimation(() => window.showInactive());
+}
+
+export function hideScreenshotOverlay(window: BrowserWindow): void {
+ withoutScreenshotAnimation(() => window.hide());
+}
+
+function withoutScreenshotAnimation(changeVisibility: () => void): void {
+ const flag = 'wm-window-animations-disabled';
+ if (process.platform !== 'win32' || app.commandLine.hasSwitch(flag)) {
+ changeVisibility();
+ return;
+ }
+ // show / hide 必须成对禁用:hide 动画会留下 opacity=0 和缩放变换,
+ // 下次禁用 show 动画时不会恢复,导致复用窗口不可见。
+ // Aura 同步读取此开关;立即恢复,不能改变其它窗口的动画策略。
+ app.commandLine.appendSwitch(flag);
+ try {
+ changeVisibility();
+ } finally {
+ app.commandLine.removeSwitch(flag);
+ }
+}
+
+export interface OverlayWindow {
+ readonly window: BrowserWindow;
+ readonly displayId: number;
+ /** 页面已挂载 (SHELL_READY)。 */
+ shellReady: boolean;
+}
+
+interface Entry extends OverlayWindow {
+ waiters: Array<(ready: boolean) => void>;
+}
+
+/**
+ * 每块显示器一个全屏框选浮层, 隐藏预热、截图时显示、结束后销毁并重新预热。
+ *
+ * 与 §3.1 独立辅助窗口基线的差异 (全局热键 + 置顶系统浮层的平台约束):
+ * - 不随主窗口挂父子关系、不进任务栏 / Dock, 置顶在屏保层级; macOS 用不激活应用的面板;
+ * - 「就绪」分两段: 预热时页面挂载, 每次截图再等定格画面绘制后才显示
+ * (见 RegionScreenshotSession); 隐藏前由页面清空画面与交互态;
+ * - 显示器增减或分辨率变化时按显示器重建, 不尝试在原窗口上迁移。
+ * - 透明浮层用后销毁, 避免下次截图继承原生窗口的合成状态; 未使用的预热壳仍可复用。
+ * 其余安全配置、sender 校验、故障隔离与有界重建照基线执行。
+ */
+export class OverlayPool {
+ private readonly byDisplay = new Map<number, Entry>();
+ private readonly byContents = new Map<number, Entry>();
+ private readonly retiring = new Map<Entry, ReturnType<typeof setTimeout>>();
+ private crashes: number[] = [];
+ private disabled = false;
+ private onGone: ((overlay: OverlayWindow) => void) | null = null;
+
+ /** 浮层窗口意外消失 (崩溃 / 被系统关闭) 时通知当前会话。 */
+ setGoneHandler(handler: (overlay: OverlayWindow) => void): void {
+ this.onGone = handler;
+ }
+
+ get isDisabled(): boolean {
+ return this.disabled;
+ }
+
+ forContents(contents: WebContents): OverlayWindow | null {
+ const entry = this.byContents.get(contents.id);
+ return entry && !entry.window.isDestroyed() ? entry : null;
+ }
+
+ /** 后台为所有显示器预热浮层; 已存在的只校正位置。 */
+ prewarm(): void {
+ if (this.disabled) return;
+ const displays = screen.getAllDisplays();
+ const ids = new Set(displays.map((d) => d.id));
+ for (const [displayId, entry] of this.byDisplay) {
+ if (!ids.has(displayId)) this.destroy(entry);
+ }
+ for (const display of displays) this.ensure(display);
+ }
+
+ /** 显示器配置变了: 全部销毁, 稍后按新配置预热。 */
+ reset(): void {
+ for (const entry of [...this.byDisplay.values()]) this.destroy(entry);
+ }
+
+ ensure(display: Display): OverlayWindow | null {
+ if (this.disabled) return null;
+ const existing = this.byDisplay.get(display.id);
+ if (existing && !existing.window.isDestroyed()) return existing;
+ if (existing) this.forget(existing);
+ try {
+ return this.create(display);
+ } catch (error) {
+ log.warn('overlay creation failed', { error });
+ this.recordCrash();
+ return null;
+ }
+ }
+
+ /** 等页面挂载; 超时返回 false。 */
+ waitForShell(overlay: OverlayWindow): Promise<boolean> {
+ if (overlay.shellReady) return Promise.resolve(true);
+ const entry = overlay as Entry;
+ return new Promise((resolve) => {
+ const timer = setTimeout(() => {
+ entry.waiters = entry.waiters.filter((w) => w !== done);
+ if (!entry.window.isDestroyed()) this.discard(entry);
+ resolve(false);
+ }, SHELL_TIMEOUT_MS);
+ const done = (ready: boolean) => {
+ clearTimeout(timer);
+ resolve(ready);
+ };
+ entry.waiters.push(done);
+ });
+ }
+
+ markShellReady(contents: WebContents, frame: Electron.WebFrameMain | null): void {
+ const entry = this.byContents.get(contents.id);
+ if (!entry || !frame || frame !== contents.mainFrame) return;
+ entry.shellReady = true;
+ for (const waiter of entry.waiters.splice(0)) waiter(true);
+ }
+
+ destroyAll(): void {
+ this.disabled = true;
+ this.reset();
+ for (const [entry, timer] of this.retiring) {
+ clearTimeout(timer);
+ this.destroy(entry);
+ }
+ this.retiring.clear();
+ }
+
+ /**
+ * 截图结束后销毁用过的透明浮层, 避免下一次截图继承原生窗口的透明度与合成状态。
+ * 先从池中移除, 即使下一次截图立即开始, 也只会取得新窗口。
+ */
+ retire(overlay: OverlayWindow): void {
+ const entry = overlay as Entry;
+ this.forget(entry);
+ const { window } = entry;
+ if (window.isDestroyed() || this.retiring.has(entry)) return;
+ window.setOpacity(0);
+ hideScreenshotOverlay(window);
+ // 让当前 export IPC handler 先返回, 再销毁 sender; 退出时由 destroyAll 同步清理。
+ this.retiring.set(entry, setTimeout(() => {
+ this.retiring.delete(entry);
+ if (!window.isDestroyed()) window.destroy();
+ }, 0));
+ }
+
+ /** 页面状态已失效,关闭后丢弃,避免下次复用已崩溃的 React 树。 */
+ discard(overlay: OverlayWindow): void {
+ this.recordCrash();
+ this.destroy(overlay as Entry);
+ }
+
+ private create(display: Display): OverlayWindow {
+ const window = createScreenshotPageWindow({
+ preload: 'regionScreenshotPreload.js',
+ query: 'regionScreenshot',
+ ...display.bounds,
+ enableLargerThanScreen: true,
+ acceptFirstMouse: true,
+ resizable: false,
+ movable: false,
+ hasShadow: false,
+ // 定格画面绘制前的底色; 窗口在画面绘制完成前保持全透明, 用户看不到它。
+ transparent: true,
+ backgroundColor: '#00000000',
+ // macOS: 不激活应用的面板。能拿键盘焦点, 但截图前的应用保持前台: 菜单栏、
+ // Dock 不跳动, 结束时不必抢回焦点, 滚动截图时触控板滚动与惯性照常交给它。
+ ...(process.platform === 'darwin' ? { type: 'panel' } : {}),
+ });
+ const entry: Entry = { window, displayId: display.id, shellReady: false, waiters: [] };
+ this.byDisplay.set(display.id, entry);
+ this.byContents.set(window.webContents.id, entry);
+ window.setVisibleOnAllWorkspaces(true, {
+ visibleOnFullScreen: true,
+ skipTransformProcessType: true,
+ });
+ window.setAlwaysOnTop(true, 'screen-saver', 1);
+ // 页面重新加载 (开发热更新、意外导航) 会丢掉会话状态: 视为这块浮层失效, 让当前会话结束,
+ // 未使用的预热壳等页面重新挂载后继续使用, 已使用的浮层随会话结束销毁。
+ window.webContents.on('did-start-loading', () => {
+ entry.shellReady = false;
+ this.onGone?.(entry);
+ });
+ window.webContents.on('render-process-gone', (_event, details) => {
+ if (window.isDestroyed()) return;
+ log.warn('overlay renderer gone', { reason: details.reason });
+ this.recordCrash();
+ this.destroy(entry);
+ });
+ window.on('unresponsive', () => {
+ log.warn('overlay became unresponsive; closing screenshot');
+ this.recordCrash();
+ this.destroy(entry);
+ });
+ window.webContents.on('did-fail-load', (_event, _code, _description, _url, isMainFrame) => {
+ if (!isMainFrame || window.isDestroyed()) return;
+ this.recordCrash();
+ this.destroy(entry);
+ });
+ window.on('closed', () => {
+ this.forget(entry);
+ this.onGone?.(entry);
+ });
+ return entry;
+ }
+
+ private recordCrash(): void {
+ const now = Date.now();
+ this.crashes = [...this.crashes.filter((t) => now - t < CRASH_WINDOW_MS), now];
+ if (this.crashes.length > CRASH_LIMIT) {
+ log.warn('overlay keeps crashing; screenshots disabled until restart');
+ this.disabled = true;
+ }
+ }
+
+ private forget(entry: Entry): void {
+ if (this.byDisplay.get(entry.displayId) === entry) this.byDisplay.delete(entry.displayId);
+ for (const [id, value] of this.byContents) {
+ if (value === entry) this.byContents.delete(id);
+ }
+ for (const waiter of entry.waiters.splice(0)) waiter(false);
+ }
+
+ private destroy(entry: Entry): void {
+ this.forget(entry);
+ // destroy 会触发 'closed', 由那里通知当前会话。
+ if (!entry.window.isDestroyed()) entry.window.destroy();
+ }
+}
diff --git a/apps/desktop/src/main/region-screenshot/pageWindow.ts b/apps/desktop/src/main/region-screenshot/pageWindow.ts
new file mode 100644
index 0000000000..fcb7289dac
--- /dev/null
+++ b/apps/desktop/src/main/region-screenshot/pageWindow.ts
@@ -0,0 +1,69 @@
+import { BrowserWindow, type BrowserWindowConstructorOptions } from 'electron';
+import path from 'node:path';
+
+import { markAppearanceSettingsReaderWindow } from '../appearance-settings-reader';
+import { createLogger } from '../logger';
+import { installExternalLinkGuards } from '../secondary-windows';
+
+const log = createLogger('region-screenshot:window');
+
+/**
+ * 框选浮层与贴图窗口共用的窗口工厂: 加载主窗口同源页面并通过 query 进入各自的
+ * 轻量入口 (renderer/index.tsx 分流), 只挂对应的专用 preload。
+ *
+ * 安全字段与 docs/dev-rules/electron-security-and-process-boundaries.md 的基线一致;
+ * 不跑 webview、不开 devTools 以外的任何放宽。
+ */
+export function createScreenshotPageWindow(
+ options: BrowserWindowConstructorOptions & { preload: string; query: string },
+): BrowserWindow {
+ const { preload, query, ...windowOptions } = options;
+ const window = new BrowserWindow({
+ show: false,
+ frame: false,
+ roundedCorners: false,
+ minimizable: false,
+ maximizable: false,
+ fullscreenable: false,
+ skipTaskbar: true,
+ autoHideMenuBar: true,
+ ...windowOptions,
+ webPreferences: {
+ preload: path.join(__dirname, preload),
+ sandbox: true,
+ contextIsolation: true,
+ nodeIntegration: false,
+ nodeIntegrationInSubFrames: false,
+ nodeIntegrationInWorker: false,
+ webSecurity: true,
+ allowRunningInsecureContent: false,
+ experimentalFeatures: false,
+ plugins: false,
+ navigateOnDragDrop: false,
+ spellcheck: false,
+ webviewTag: false,
+ // 隐藏时也要及时处理下一次截图的定格画面, 不能被后台节流拖慢弹出。
+ backgroundThrottling: false,
+ },
+ });
+ window.setMenuBarVisibility(false);
+ installExternalLinkGuards(window);
+ // 只读外观快照 (字体 / 字号), 让浮层与贴图的界面和主窗口一致; 不授予任何写入能力。
+ markAppearanceSettingsReaderWindow(window);
+ const load = MAIN_WINDOW_VITE_DEV_SERVER_URL
+ ? (() => {
+ const url = new URL(MAIN_WINDOW_VITE_DEV_SERVER_URL);
+ url.searchParams.set(query, '1');
+ return window.loadURL(url.toString());
+ })()
+ : window.loadFile(path.join(__dirname, `../renderer/${MAIN_WINDOW_VITE_NAME}/index.html`), {
+ query: { [query]: '1' },
+ });
+ void load.catch((error: unknown) => {
+ log.warn('screenshot page load rejected', {
+ query,
+ error: error instanceof Error ? error.message : String(error),
+ });
+ });
+ return window;
+}
diff --git a/apps/desktop/src/main/region-screenshot/pins.ts b/apps/desktop/src/main/region-screenshot/pins.ts
new file mode 100644
index 0000000000..6146419b67
--- /dev/null
+++ b/apps/desktop/src/main/region-screenshot/pins.ts
@@ -0,0 +1,296 @@
+import {
+ clipboard,
+ ipcMain,
+ Menu,
+ screen,
+ type BrowserWindow,
+ type IpcMainEvent,
+ type NativeImage,
+ type Rectangle,
+} from 'electron';
+
+import { createLogger } from '../logger';
+import { activeOwnerScopeKey } from '../appSessionState';
+import { getResolvedMainLocale, t } from '../i18n';
+import {
+ REGION_SCREENSHOT_PIN_CHANNEL as C,
+ REGION_SCREENSHOT_PIN_COMMANDS,
+ type RegionScreenshotPinCommand,
+ type RegionScreenshotPinInit,
+ type RegionScreenshotPinState,
+} from '../../shared/regionScreenshot';
+import { handOffScreenshotToTask } from './compose';
+import { createScreenshotPageWindow } from './pageWindow';
+import { saveScreenshotImage } from './save';
+
+const log = createLogger('region-screenshot:pins');
+
+const MIN_ZOOM = 0.1;
+const MAX_ZOOM = 5;
+const ZOOM_STEP = 1.1;
+const MIN_OPACITY = 0.2;
+const OPACITY_STEP = 0.1;
+/** 同时存在的贴图上限; 超出时关闭最早的一张。 */
+const MAX_PINS = 32;
+
+interface Pin {
+ ownerScope: string;
+ window: BrowserWindow;
+ image: NativeImage;
+ /** 首次显示的位置 (全局 DIP), 即截图时选区所在处。 */
+ initialBounds: Rectangle;
+ /** 原始大小 (DIP)。 */
+ base: { width: number; height: number };
+ zoom: number;
+ opacity: number;
+ passThrough: boolean;
+ drag: { cursor: Electron.Point; position: [number, number] } | null;
+}
+
+/**
+ * 贴图: 把截图钉在屏幕最上层。每张贴图一个独立窗口, 关闭即销毁 —— 这是按内容
+ * 多实例、内容关掉即结束的窗口 (同右侧栏页签弹出窗口), 不做隐藏复用; 页面在图
+ * 绘制完成后才显示。所有 IPC 按 sender 反查贴图, 页面不能指定别的贴图。
+ * 2026-10-26 用户选择按需建窗:不常驻备用 renderer,接受首次贴图的加载时间;
+ * 这仅豁免 §3.1 的预热条款,仍保留首帧握手、来源校验和失败关闭。
+ */
+const pins = new Map<number, Pin>();
+let ipcRegistered = false;
+
+function pinFor(event: IpcMainEvent): Pin | null {
+ if (!event.senderFrame || event.senderFrame !== event.sender.mainFrame) return null;
+ const pin = pins.get(event.sender.id);
+ return pin && !pin.window.isDestroyed() ? pin : null;
+}
+
+function sendState(pin: Pin): void {
+ const state: RegionScreenshotPinState = {
+ opacity: pin.opacity,
+ passThrough: pin.passThrough,
+ zoom: pin.zoom,
+ };
+ if (!pin.window.isDestroyed()) pin.window.webContents.send(C.STATE, state);
+}
+
+export function openPin(image: NativeImage, bounds: Rectangle, ownerScope = activeOwnerScopeKey()): void {
+ // A stitched image can be much taller than the original selection. Fit its
+ // actual aspect ratio into the target screen, without changing the pixels.
+ const size = image.getSize();
+ const area = screen.getDisplayMatching(bounds).workArea;
+ const ratio = Math.min(bounds.width / size.width, area.width / size.width, area.height / size.height);
+ const width = Math.max(1, Math.round(size.width * ratio));
+ const height = Math.max(1, Math.round(size.height * ratio));
+ bounds = { width, height,
+ x: Math.round(Math.max(area.x, Math.min(bounds.x, area.x + area.width - width))),
+ y: Math.round(Math.max(area.y, Math.min(bounds.y, area.y + area.height - height))),
+ };
+ if (pins.size >= MAX_PINS) {
+ const oldest = pins.values().next().value;
+ if (oldest && !oldest.window.isDestroyed()) oldest.window.close();
+ }
+ const window = createScreenshotPageWindow({
+ preload: 'regionScreenshotPinPreload.js',
+ query: 'regionScreenshotPin',
+ ...bounds,
+ resizable: false,
+ hasShadow: true,
+ alwaysOnTop: true,
+ // 图绘制前的底色; 窗口在图绘制完成后才显示。
+ backgroundColor: '#000000',
+ });
+ window.setAlwaysOnTop(true, 'floating');
+ const pin: Pin = {
+ ownerScope,
+ window,
+ image,
+ initialBounds: bounds,
+ base: { width: bounds.width, height: bounds.height },
+ zoom: 1,
+ opacity: 1,
+ passThrough: false,
+ drag: null,
+ };
+ const id = window.webContents.id;
+ pins.set(id, pin);
+ window.on('closed', () => pins.delete(id));
+ window.webContents.on('render-process-gone', () => {
+ if (!window.isDestroyed()) window.destroy();
+ });
+ // 没有内容的窗口不能显示成黑块;失败只关闭这张贴图。
+ const fallback = setTimeout(() => { if (!window.isDestroyed()) window.destroy(); }, 3000);
+ window.once('show', () => clearTimeout(fallback));
+ window.once('closed', () => clearTimeout(fallback));
+ window.on('unresponsive', () => { if (!window.isDestroyed()) window.destroy(); });
+}
+
+function show(pin: Pin): void {
+ const bounds = pin.initialBounds;
+ const { window } = pin;
+ if (window.isDestroyed() || window.isVisible()) return;
+ window.showInactive();
+ // 混合 DPI 下首次定位可能按错误的缩放落位, 显示后再校正一次。
+ window.setBounds(bounds, false);
+}
+
+export function closeAllPins(): void {
+ for (const pin of [...pins.values()]) {
+ if (!pin.window.isDestroyed()) pin.window.close();
+ }
+}
+
+function setZoom(pin: Pin, zoom: number, anchor?: { x: number; y: number }): void {
+ const next = Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, zoom));
+ const bounds = pin.window.getBounds();
+ const width = Math.max(8, Math.round(pin.base.width * next));
+ const height = Math.max(8, Math.round(pin.base.height * next));
+ const ax = anchor ? anchor.x : bounds.width / 2;
+ const ay = anchor ? anchor.y : bounds.height / 2;
+ pin.zoom = next;
+ pin.window.setBounds({
+ x: Math.round(bounds.x + ax - (ax * width) / bounds.width),
+ y: Math.round(bounds.y + ay - (ay * height) / bounds.height),
+ width,
+ height,
+ });
+ sendState(pin);
+}
+
+function setOpacity(pin: Pin, opacity: number): void {
+ pin.opacity = Math.round(Math.min(1, Math.max(MIN_OPACITY, opacity)) * 10) / 10;
+ pin.window.setOpacity(pin.opacity);
+ sendState(pin);
+}
+
+function setPassThrough(pin: Pin, passThrough: boolean): void {
+ pin.passThrough = passThrough;
+ // 穿透时仍转发指针移动, 页面才能在指针停到「恢复」按钮上时把点击要回来。
+ if (passThrough) pin.window.setIgnoreMouseEvents(true, { forward: true });
+ else pin.window.setIgnoreMouseEvents(false);
+ sendState(pin);
+}
+
+function runCommand(pin: Pin, command: RegionScreenshotPinCommand): void {
+ switch (command) {
+ case 'copy':
+ clipboard.writeImage(pin.image);
+ return;
+ case 'save':
+ void saveScreenshotImage(pin.image);
+ return;
+ case 'ask':
+ void handOffScreenshotToTask(pin.image, 'ask', pin.ownerScope).catch((error: unknown) => {
+ log.warn('pin hand-off failed', { error });
+ });
+ return;
+ case 'close':
+ pin.window.close();
+ return;
+ case 'unlock':
+ setPassThrough(pin, false);
+ return;
+ case 'zoom-reset':
+ setZoom(pin, 1);
+ return;
+ }
+}
+
+function popupMenu(pin: Pin): void {
+ const opacityItems = [1, 0.8, 0.6, 0.4].map((value) => ({
+ label: `${Math.round(value * 100)}%`,
+ type: 'radio' as const,
+ checked: Math.abs(pin.opacity - value) < 0.05,
+ click: () => setOpacity(pin, value),
+ }));
+ const menu = Menu.buildFromTemplate([
+ { label: t('regionScreenshot.pin.copy'), accelerator: 'CmdOrCtrl+C', click: () => runCommand(pin, 'copy') },
+ { label: t('regionScreenshot.pin.save'), accelerator: 'CmdOrCtrl+S', click: () => runCommand(pin, 'save') },
+ { label: t('regionScreenshot.pin.ask'), click: () => runCommand(pin, 'ask') },
+ { type: 'separator' },
+ { label: t('regionScreenshot.pin.opacity'), submenu: opacityItems },
+ {
+ label: t('regionScreenshot.pin.originalSize'),
+ accelerator: '0',
+ enabled: pin.zoom !== 1,
+ click: () => runCommand(pin, 'zoom-reset'),
+ },
+ {
+ label: t('regionScreenshot.pin.passThrough'),
+ type: 'checkbox',
+ checked: pin.passThrough,
+ click: () => setPassThrough(pin, !pin.passThrough),
+ },
+ { type: 'separator' },
+ { label: t('regionScreenshot.pin.close'), accelerator: 'Esc', click: () => runCommand(pin, 'close') },
+ { label: t('regionScreenshot.pin.closeAll'), click: closeAllPins },
+ ]);
+ menu.popup({ window: pin.window });
+}
+
+const finiteNumber = (value: unknown): value is number =>
+ typeof value === 'number' && Number.isFinite(value);
+
+export function registerPinIpc(): void {
+ if (ipcRegistered) return;
+ ipcRegistered = true;
+ ipcMain.on(C.SHELL_READY, (event) => {
+ const pin = pinFor(event);
+ if (!pin) return;
+ const size = pin.image.getSize();
+ const bitmap = pin.image.toBitmap();
+ const init: RegionScreenshotPinInit = {
+ locale: getResolvedMainLocale(),
+ image: {
+ width: size.width,
+ height: size.height,
+ data: new Uint8Array(bitmap.buffer, bitmap.byteOffset, bitmap.byteLength) as Uint8Array<ArrayBuffer>,
+ },
+ };
+ event.sender.send(C.INIT, init);
+ sendState(pin);
+ });
+ ipcMain.on(C.PAINTED, (event) => {
+ const pin = pinFor(event);
+ if (pin) show(pin);
+ });
+ ipcMain.on(C.DRAG_START, (event) => {
+ const pin = pinFor(event);
+ if (!pin) return;
+ const [x, y] = pin.window.getPosition();
+ pin.drag = { cursor: screen.getCursorScreenPoint(), position: [x, y] };
+ });
+ ipcMain.on(C.DRAG_MOVE, (event) => {
+ const pin = pinFor(event);
+ if (!pin?.drag) return;
+ const cursor = screen.getCursorScreenPoint();
+ pin.window.setPosition(
+ Math.round(pin.drag.position[0] + cursor.x - pin.drag.cursor.x),
+ Math.round(pin.drag.position[1] + cursor.y - pin.drag.cursor.y),
+ );
+ });
+ ipcMain.on(C.ZOOM, (event, steps: unknown, x: unknown, y: unknown) => {
+ const pin = pinFor(event);
+ if (!pin || !finiteNumber(steps) || !finiteNumber(x) || !finiteNumber(y)) return;
+ const clamped = Math.max(-5, Math.min(5, steps));
+ setZoom(pin, pin.zoom * ZOOM_STEP ** clamped, { x, y });
+ });
+ ipcMain.on(C.OPACITY, (event, steps: unknown) => {
+ const pin = pinFor(event);
+ if (!pin || !finiteNumber(steps)) return;
+ setOpacity(pin, pin.opacity + OPACITY_STEP * Math.max(-5, Math.min(5, steps)));
+ });
+ ipcMain.on(C.MENU, (event) => {
+ const pin = pinFor(event);
+ if (pin) popupMenu(pin);
+ });
+ ipcMain.on(C.COMMAND, (event, command: unknown) => {
+ const pin = pinFor(event);
+ if (!pin || !(REGION_SCREENSHOT_PIN_COMMANDS as readonly unknown[]).includes(command)) return;
+ runCommand(pin, command as RegionScreenshotPinCommand);
+ });
+ ipcMain.on(C.UNLOCK_HOVER, (event, hovering: unknown) => {
+ const pin = pinFor(event);
+ if (!pin?.passThrough) return;
+ if (hovering === true) pin.window.setIgnoreMouseEvents(false);
+ else pin.window.setIgnoreMouseEvents(true, { forward: true });
+ });
+}
diff --git a/apps/desktop/src/main/region-screenshot/recordingClipboard.ts b/apps/desktop/src/main/region-screenshot/recordingClipboard.ts
new file mode 100644
index 0000000000..e5c8de4db9
--- /dev/null
+++ b/apps/desktop/src/main/region-screenshot/recordingClipboard.ts
@@ -0,0 +1,45 @@
+import { integrationCachePut } from '../cindy-media/integrationCache';
+import { removeRefsExceptHash } from '../cindy-media/ledger';
+import { sniffMediaMime } from '../cindy-media/sniffMediaMime';
+import { getCurrentDbClientSnapshot } from '../localDb/client/current';
+import { captureDataOwnerBroadcastScope, isDataOwnerBroadcastScopeCurrent } from '../device-link/broadcast-tap';
+import { copyFileToClipboardMacOS, copyFileToClipboardWindows } from '../fileClipboard';
+import { createLogger } from '../logger';
+import { validRecordingBytes } from '../../shared/regionCapture';
+
+const log = createLogger('region-screenshot:clipboard');
+const REF = 'recording-clipboard:latest';
+
+/** Retain the last successfully copied clip beyond preview close/app exit.
+ * Replacement releases only our old reference; shared bytes use normal recycling. */
+export async function copyRegionRecording(bytes: Uint8Array, format: 'webm' | 'gif', isCurrent: () => boolean): Promise<void> {
+ if (process.platform !== 'win32' && process.platform !== 'darwin') throw new Error('Recording clipboard unavailable');
+ const mimeType = sniffMediaMime(bytes);
+ if (!validRecordingBytes(bytes, format) || mimeType !== (format === 'gif' ? 'image/gif' : 'video/webm'))
+ throw new Error('Invalid recording');
+ const snapshot = getCurrentDbClientSnapshot();
+ if (!snapshot) throw new Error('Recording storage unavailable');
+ const owner = captureDataOwnerBroadcastScope();
+ const assertStillValid = () => {
+ if (!isCurrent() || getCurrentDbClientSnapshot() !== snapshot || !isDataOwnerBroadcastScopeCurrent(owner))
+ throw new Error('Recording clipboard cancelled');
+ };
+ assertStillValid();
+ const db = snapshot.client.drizzle;
+ const media = await integrationCachePut({
+ buffer: bytes, mimeType, isCache: false,
+ cacheKey: REF, integration: 'recording-clipboard', assertStillValid,
+ }, db);
+ try {
+ assertStillValid();
+ if (process.platform === 'win32') await copyFileToClipboardWindows(media.absPath);
+ else await copyFileToClipboardMacOS(media.absPath);
+ } catch (error) {
+ await media.rollbackRef().catch(() => { log.warn('recording clipboard reference rollback failed'); });
+ throw error;
+ }
+ // Clipboard now points to these bytes. Retain them even if the page closes or
+ // owner changes while the OS helper finishes. Cleanup stays on the captured DB.
+ await removeRefsExceptHash({ refKind: 'integration-cache', refId: REF, keepHash: media.hash }, db)
+ .catch(() => { log.warn('old recording clipboard reference cleanup failed'); });
+}
diff --git a/apps/desktop/src/main/region-screenshot/recordingPreview.ts b/apps/desktop/src/main/region-screenshot/recordingPreview.ts
new file mode 100644
index 0000000000..22eb835afc
--- /dev/null
+++ b/apps/desktop/src/main/region-screenshot/recordingPreview.ts
@@ -0,0 +1,137 @@
+import { app, ipcMain, nativeTheme, screen, type BrowserWindow, type Display, type IpcMainEvent, type IpcMainInvokeEvent } from 'electron';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { ResourceUsageWindowController } from '../resource-usage-window/controller';
+import { markPlaybackFullscreenWindow } from '../remote-desktop/capturePermissions';
+import { getResolvedMainLocale, t } from '../i18n';
+import { RECORDING_PREVIEW_CHANNEL as C, validRecordingBytes, type RecordingPreviewDocument } from '../../shared/regionCapture';
+import { createScreenshotPageWindow } from './pageWindow';
+import { saveRegionRecording } from './save';
+import { copyRegionRecording } from './recordingClipboard';
+import { createLogger } from '../logger';
+import { activeOwnerScopeKey, isAppSessionBoundaryPending, onAppSessionInvalidated } from '../appSessionState';
+
+const log = createLogger('region-screenshot:preview');
+
+/** Only finished clip bytes enter this window; it has no screen or keyboard access. */
+export class RecordingPreview {
+ private window: BrowserWindow | null = null;
+ private ready = false;
+ private document: RecordingPreviewDocument | null = null;
+ private ownerScope: string | null = null;
+ private saving = false;
+ private readonly controller: ResourceUsageWindowController;
+ private readonly unsubscribeOwner: () => void;
+
+ constructor() {
+ this.controller = new ResourceUsageWindowController({
+ createWindow: () => {
+ this.ready = false;
+ const window = createScreenshotPageWindow({
+ width: 900, height: 660, minWidth: 480, minHeight: 320,
+ frame: false, roundedCorners: true, resizable: true,
+ minimizable: true, maximizable: true, fullscreenable: true, skipTaskbar: false,
+ icon: app.isPackaged ? path.join(process.resourcesPath, 'icon.png') : path.join(__dirname, '../../resources/icon.png'),
+ backgroundColor: nativeTheme.shouldUseDarkColors ? '#1f1f1e' : '#f8f8f6',
+ preload: 'recordingPreviewPreload.js', query: 'recordingPreview',
+ });
+ this.window = window;
+ markPlaybackFullscreenWindow(window);
+ window.on('closed', () => { if (this.window === window) { this.window = null; this.ready = false; } });
+ return window;
+ },
+ prewarmWork: false, pauseWhenHidden: false, activityChannel: C.ACTIVITY,
+ isOpenSender: (sender) => sender === this.window?.webContents,
+ resolveNativeTitle: () => t('regionScreenshot.live.preview'),
+ onBeforeShow: () => {
+ // Capture panels leave the captured app active. Activate only when the
+ // requested preview is presented, then let the controller focus its window.
+ if (process.platform === 'darwin') app.focus({ steal: true });
+ },
+ onCloseRequested: () => this.close(),
+ onUnavailable: () => { this.document = null; },
+ });
+ this.unsubscribeOwner = onAppSessionInvalidated(() => {
+ this.document = null;
+ this.ownerScope = null;
+ // Destroy the renderer too: an old clip must not remain playable after logout.
+ // Do not wait for an outstanding save dialog or clipboard operation.
+ if (this.window && !this.window.isDestroyed()) this.window.destroy();
+ });
+ }
+
+ prewarm(): void { this.controller.prewarm(); }
+ dispose(): void { this.unsubscribeOwner(); this.document = null; this.ownerScope = null; this.controller.dispose(); }
+
+ open(bytes: Uint8Array<ArrayBuffer>, format: 'webm' | 'gif', display: Display, ownerScope = activeOwnerScopeKey()): boolean {
+ if (this.document || this.saving || isAppSessionBoundaryPending()
+ || ownerScope !== activeOwnerScopeKey() || !validRecordingBytes(bytes, format)) return false;
+ this.controller.prewarm();
+ const window = this.window;
+ if (!window || window.isDestroyed()) return false;
+ this.ownerScope = ownerScope;
+ this.document = { token: randomUUID(), locale: getResolvedMainLocale(), bytes, format };
+ const area = screen.getDisplayMatching(display.bounds).workArea;
+ const width = Math.min(900, area.width), height = Math.min(660, area.height);
+ if (!window.isMaximized()) window.setBounds({ x: Math.round(area.x + (area.width - width) / 2), y: Math.round(area.y + (area.height - height) / 2), width, height });
+ this.controller.resetPresentation();
+ if (this.ready) window.webContents.send(C.BEGIN, this.document);
+ if (this.controller.open(window.webContents)) return true;
+ this.document = null;
+ return false;
+ }
+
+ private owns(event: IpcMainEvent | IpcMainInvokeEvent, token?: unknown): boolean {
+ return !!this.window && !this.window.isDestroyed() && event.sender === this.window.webContents
+ && event.senderFrame === event.sender.mainFrame
+ && (!this.document || (!isAppSessionBoundaryPending() && this.ownerScope === activeOwnerScopeKey()))
+ && (token === undefined || token === this.document?.token);
+ }
+
+ private close(): void {
+ if (this.saving) return;
+ this.document = null;
+ if (!this.window || this.window.isDestroyed()) return;
+ this.window.webContents.send(C.END);
+ this.controller.close(this.window.webContents);
+ this.controller.resetPresentation();
+ }
+
+ registerIpc(): void {
+ ipcMain.on(C.READY, (event) => {
+ if (!this.owns(event)) return;
+ this.ready = true;
+ this.controller.markRendererReady(event.sender);
+ if (this.document) event.sender.send(C.BEGIN, this.document);
+ });
+ ipcMain.on(C.FAILED, (event) => { if (this.owns(event)) this.controller.rendererFailed(event.sender); });
+ ipcMain.on(C.PAINTED, (event, token: unknown) => {
+ if (typeof token === 'string' && this.document && this.owns(event, token)) this.controller.markPresentationReady(event.sender);
+ });
+ ipcMain.on(C.CLOSE, (event, token: unknown) => {
+ if (typeof token === 'string' && this.document && this.owns(event, token)) this.close();
+ });
+ ipcMain.on(C.MINIMIZE, (event, token: unknown) => {
+ if (typeof token === 'string' && this.document && this.owns(event, token)) this.window?.minimize();
+ });
+ ipcMain.handle(C.SAVE, async (event, token: unknown) => {
+ const doc = this.document;
+ if (!doc || this.saving || typeof token !== 'string' || !this.owns(event, token)) return false;
+ this.saving = true;
+ try { return await saveRegionRecording(doc.bytes, doc.format, () => this.document === doc && this.owns(event, token)); }
+ finally { this.saving = false; }
+ });
+ ipcMain.handle(C.COPY, async (event, token: unknown) => {
+ const doc = this.document;
+ if (!doc || this.saving || typeof token !== 'string' || !this.owns(event, token)) return false;
+ this.saving = true;
+ try {
+ await copyRegionRecording(doc.bytes, doc.format, () => this.document === doc && this.owns(event, token));
+ return true;
+ } catch {
+ log.warn('recording clipboard copy failed');
+ return false;
+ } finally { this.saving = false; }
+ });
+ }
+}
diff --git a/apps/desktop/src/main/region-screenshot/save.ts b/apps/desktop/src/main/region-screenshot/save.ts
new file mode 100644
index 0000000000..f077ed5763
--- /dev/null
+++ b/apps/desktop/src/main/region-screenshot/save.ts
@@ -0,0 +1,72 @@
+import { app, dialog, type NativeImage } from 'electron';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { createLogger } from '../logger';
+import { t } from '../i18n';
+
+const log = createLogger('region-screenshot:save');
+
+/** 本次运行里上一次保存的目录; 首次用系统「图片」目录。 */
+let lastDirectory: string | null = null;
+
+const pad = (value: number) => String(value).padStart(2, '0');
+
+function defaultFileName(now = new Date()): string {
+ const stamp = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(
+ now.getHours(),
+ )}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+ return `${t('regionScreenshot.saveFileName')} ${stamp}.png`;
+}
+
+/**
+ * 弹出系统保存框把截图存为 PNG / JPEG (按用户选的扩展名)。用户取消返回 false;
+ * 写入失败给出系统提示, 不抛错。
+ */
+export async function saveScreenshotImage(image: NativeImage): Promise<boolean> {
+ const directory = lastDirectory ?? app.getPath('pictures');
+ const result = await dialog.showSaveDialog({
+ defaultPath: path.join(directory, defaultFileName()),
+ filters: [
+ { name: 'PNG', extensions: ['png'] },
+ { name: 'JPEG', extensions: ['jpg', 'jpeg'] },
+ ],
+ });
+ if (result.canceled || !result.filePath) return false;
+ const extension = path.extname(result.filePath).toLowerCase();
+ const isJpeg = extension === '.jpg' || extension === '.jpeg';
+ const filePath = extension ? result.filePath : `${result.filePath}.png`;
+ try {
+ await fs.writeFile(filePath, isJpeg ? image.toJPEG(92) : image.toPNG());
+ lastDirectory = path.dirname(filePath);
+ return true;
+ } catch (error) {
+ log.warn('screenshot save failed', { error });
+ void dialog.showMessageBox({
+ type: 'error',
+ message: t('regionScreenshot.saveFailed'),
+ detail: error instanceof Error ? error.message : String(error),
+ noLink: true,
+ });
+ return false;
+ }
+}
+
+/** Export only to a path selected in the native dialog; keep bytes in memory on cancellation. */
+export async function saveRegionRecording(bytes: Uint8Array, format: 'webm' | 'gif', isCurrent: () => boolean = () => true): Promise<boolean> {
+ if (!isCurrent()) return false;
+ const result = await dialog.showSaveDialog({
+ defaultPath: path.join(lastDirectory ?? app.getPath('videos'), `${t(`regionScreenshot.live.${format === 'gif' ? 'gif' : 'video'}`)} ${Date.now()}.${format}`),
+ filters: [{ name: format === 'gif' ? 'GIF' : 'WebM', extensions: [format] }],
+ });
+ if (result.canceled || !result.filePath || !isCurrent()) return false;
+ const filePath = result.filePath.toLowerCase().endsWith(`.${format}`) ? result.filePath : `${result.filePath}.${format}`;
+ try {
+ await fs.writeFile(filePath, bytes);
+ lastDirectory = path.dirname(filePath);
+ return true;
+ } catch {
+ void dialog.showMessageBox({ type: 'error', message: t('regionScreenshot.saveFailed'), noLink: true });
+ return false;
+ }
+}
diff --git a/apps/desktop/src/main/region-screenshot/session.ts b/apps/desktop/src/main/region-screenshot/session.ts
new file mode 100644
index 0000000000..d69f5785e6
--- /dev/null
+++ b/apps/desktop/src/main/region-screenshot/session.ts
@@ -0,0 +1,611 @@
+import {
+ clipboard,
+ nativeImage,
+ screen,
+ systemPreferences,
+ type Display,
+ type NativeImage,
+ type WebContents,
+} from 'electron';
+import { randomUUID } from 'node:crypto';
+
+import { createLogger } from '../logger';
+import { getResolvedMainLocale } from '../i18n';
+import { acquireOverlayEscape } from '../overlayEscape';
+import { throwIpcError } from '../utils/ipcValidate';
+import { recordingControlsBounds, scrollCaptureLayout, scrollPreviewBounds, validRecordingBytes, type ScrollCaptureLayout, type RegionCaptureBegin, type RegionCaptureFrame, type RegionCaptureMode } from '../../shared/regionCapture';
+import { captureLiveRegion, RegionVideoCapture } from './liveCapture';
+import { saveRegionRecording } from './save';
+import {
+ intersectRegion,
+ isRegionScreenshotAction,
+ normalizeRegionSelection,
+ regionChromeArea,
+ regionSelectionToImageCrop,
+ REGION_SCREENSHOT_CHANNEL,
+ validateRegionBitmap,
+ type RegionRect,
+ type RegionScreenshotAction,
+ type RegionScreenshotBegin,
+ type RegionScreenshotBitmap,
+ type RegionScreenshotWindow,
+} from '../../shared/regionScreenshot';
+import { hideScreenshotOverlay, showScreenshotOverlay, type OverlayPool, type OverlayWindow } from './overlays';
+import type { SnapshotHelper, SnapshotWindow } from './snapshotHost';
+
+const log = createLogger('region-screenshot:session');
+
+/** 未绘制的浮层最多等这么久,超时隐藏并退出,不能强行展示黑屏。 */
+const REVEAL_FALLBACK_MS = 1500;
+const MAX_COLOR_TEXT = 64;
+
+export interface DisplayCapture {
+ display: Display;
+ /** 定格原图 (desktopCapturer 缩略图), 浮层显示与最终导出的唯一来源。 */
+ image: NativeImage;
+}
+
+export interface RegionScreenshotResult {
+ ownerScope?: string;
+ action: RegionScreenshotAction;
+ image: NativeImage;
+ display: Display;
+ /** 选区 (显示器内 DIP)。 */
+ selection: RegionRect;
+}
+
+interface Member {
+ overlay: OverlayWindow;
+ capture: DisplayCapture;
+ painted: boolean;
+}
+
+export interface RegionScreenshotSessionDeps {
+ pool: OverlayPool;
+ captures: readonly DisplayCapture[];
+ helper: SnapshotHelper;
+ /** 定格时的窗口列表 (识别程序的坐标系), 下标即页面看到的窗口 id。 */
+ windows: readonly SnapshotWindow[];
+ lastRegions: ReadonlyMap<number, RegionRect>;
+ /** macOS: 每块显示器顶部被刘海占用的高度 (DIP), 按 Display.id。 */
+ topInsets?: ReadonlyMap<number, number>;
+ onResult: (result: RegionScreenshotResult) => void;
+ openEditor?: (image: RegionScreenshotBitmap, display: Display, selection: RegionRect) => boolean;
+ openRecording?: (bytes: Uint8Array<ArrayBuffer>, format: 'webm' | 'gif', display: Display) => boolean;
+ onClosed: () => void;
+}
+
+/** 识别程序的矩形 → 全局 DIP。Windows 程序按物理像素回报, macOS 已是 DIP。 */
+function toGlobalDip([left, top, right, bottom]: SnapshotWindow['rect']): RegionRect {
+ const rect = { x: left, y: top, width: right - left, height: bottom - top };
+ return process.platform === 'win32' ? screen.screenToDipRect(null, rect) : rect;
+}
+
+function toLocal(rect: RegionRect, display: Display): RegionRect {
+ return { ...rect, x: rect.x - display.bounds.x, y: rect.y - display.bounds.y };
+}
+
+/**
+ * 一次框选截图: 每块已定格的显示器借用一个预热浮层, 用户在其中一块上完成选区与
+ * 标注后, 页面把最终图交回来, 会话结束后隐藏并销毁浮层, 再执行动作。一次性对象。
+ */
+export class RegionScreenshotSession {
+ readonly token = randomUUID();
+ private readonly members = new Map<number, Member>();
+ private closed = false;
+ private handedToEditor = false;
+ private exporting = false;
+ private videoCapture: RegionVideoCapture | null = null;
+ private recordingControls: RegionRect | null = null;
+ private draggingControls = false;
+ private live: { member: Member; selection: RegionRect; mode: RegionCaptureMode; sampling: boolean; lastSample: number; editing: boolean; layout: ScrollCaptureLayout | null; automatic: boolean; target: SnapshotWindow | null; ignoring: boolean; previewHeight: number } | null = null;
+ private scrollPointerTimer: ReturnType<typeof setInterval> | null = null;
+ private revealTimer: ReturnType<typeof setTimeout> | null = null;
+ private releaseEscapeShortcut: (() => void) | null = null;
+ private readonly onDisplaysChanged = () => {
+ log.info('displays changed during screenshot, cancelling');
+ this.close();
+ };
+ private readonly onDisplayMetricsChanged = (
+ _event: Electron.Event,
+ _display: Display,
+ metrics: string[],
+ ) => {
+ if (metrics.some((metric) => ['bounds', 'scaleFactor', 'rotation'].includes(metric)))
+ this.onDisplaysChanged();
+ };
+
+ constructor(private readonly deps: RegionScreenshotSessionDeps) {}
+
+ get isClosed(): boolean {
+ return this.closed;
+ }
+
+ get hasEditor(): boolean { return this.handedToEditor; }
+
+ /** 打开浮层; 一块屏都没准备好时返回 false 并结束会话。 */
+ async open(): Promise<boolean> {
+ screen.on('display-added', this.onDisplaysChanged);
+ screen.on('display-removed', this.onDisplaysChanged);
+ screen.on('display-metrics-changed', this.onDisplayMetricsChanged);
+ const locale = getResolvedMainLocale();
+ const cursor = screen.getCursorScreenPoint();
+ for (const capture of this.deps.captures) {
+ const overlay = this.deps.pool.ensure(capture.display);
+ if (!overlay || !(await this.deps.pool.waitForShell(overlay)) || this.closed) continue;
+ if (overlay.window.isDestroyed()) continue;
+ this.members.set(overlay.window.webContents.id, { overlay, capture, painted: false });
+ }
+ if (this.closed) return false;
+ if (this.members.size === 0) {
+ log.warn('no overlay became ready');
+ this.close();
+ return false;
+ }
+ // 先以全透明显示: 页面在可见状态下才会合成新画面, 画完 (PAINTED) 再显示,
+ // 避免闪出上一次截图残留的合成帧或底色。
+ for (const { overlay, capture } of this.members.values()) {
+ const { window } = overlay;
+ window.setOpacity(0);
+ window.setBounds(capture.display.bounds, false);
+ showScreenshotOverlay(window);
+ // 混合 DPI 下首次定位可能按错误的缩放落位, 显示后按显示器 bounds 再校正一次。
+ window.setBounds(capture.display.bounds, false);
+ }
+ this.revealTimer = setTimeout(() => this.reveal(), REVEAL_FALLBACK_MS);
+ this.holdEscape();
+ // 所有屏幕的位置稳定后才发送画面。否则快的 renderer 会在另一块屏还等
+ // SHELL_READY 时提前 PAINTED / reveal,随后又被隐藏、定位,造成整屏跳动。
+ for (const { overlay, capture } of this.members.values()) {
+ overlay.window.webContents.send(
+ REGION_SCREENSHOT_CHANNEL.BEGIN,
+ this.beginPayload(capture, locale, cursor),
+ );
+ }
+ return true;
+ }
+
+ private holdEscape(): void {
+ if (this.closed || this.releaseEscapeShortcut) return;
+ // 整次截图持有 Esc,优先于语音浮层;即使 renderer 失效仍可退出。
+ try {
+ this.releaseEscapeShortcut = acquireOverlayEscape(() => {
+ const focused = [...this.members.values()].find(
+ ({ overlay }) => !overlay.window.isDestroyed() && overlay.window.isFocused(),
+ );
+ if (!focused) {
+ this.close();
+ return;
+ }
+ // OS 按键只注册一次,聚焦浮层时把 Esc 交给原有编辑/菜单处理;
+ // 无焦点时直接退出,renderer 卡死由窗口 unresponsive 路径结束。
+ focused.overlay.window.webContents.sendInputEvent({ type: 'keyDown', keyCode: 'Escape' });
+ focused.overlay.window.webContents.sendInputEvent({ type: 'keyUp', keyCode: 'Escape' });
+ }, 10);
+ } catch (error) {
+ log.warn('temporary Escape registration failed', { error });
+ }
+ }
+
+ private beginPayload(
+ capture: DisplayCapture,
+ locale: string,
+ cursor: Electron.Point,
+ ): RegionScreenshotBegin {
+ const { display, image } = capture;
+ const local = { x: cursor.x - display.bounds.x, y: cursor.y - display.bounds.y };
+ const cursorOnDisplay =
+ local.x >= 0 &&
+ local.y >= 0 &&
+ local.x < display.bounds.width &&
+ local.y < display.bounds.height;
+ const size = image.getSize();
+ const viewport = { width: display.bounds.width, height: display.bounds.height };
+ const windows: RegionScreenshotWindow[] = [];
+ this.deps.windows.forEach((window, id) => {
+ const rect = intersectRegion(toLocal(toGlobalDip(window.rect), display), viewport);
+ if (rect) windows.push({ id, rect });
+ });
+ const bitmap = image.toBitmap();
+ return {
+ token: this.token,
+ locale,
+ viewport,
+ scaleFactor: display.scaleFactor,
+ frame: {
+ width: size.width,
+ height: size.height,
+ data: new Uint8Array(
+ bitmap.buffer,
+ bitmap.byteOffset,
+ bitmap.byteLength,
+ ) as Uint8Array<ArrayBuffer>,
+ },
+ windows,
+ lastRegion: this.deps.lastRegions.get(display.id) ?? null,
+ cursor: cursorOnDisplay ? local : null,
+ safeArea: this.chromeArea(display),
+ };
+ }
+
+ /** 界面元素 (工具条、预览、控制条) 可用的区域: 避开菜单栏、刘海与 Dock / 任务栏。 */
+ private chromeArea(display: Display): RegionRect {
+ return regionChromeArea(display.bounds, display.workArea ?? display.bounds, this.deps.topInsets?.get(display.id) ?? 0);
+ }
+
+ /** 只认本次会话借用的浮层顶层 frame, 且 token 必须是本次会话的。 */
+ private member(
+ sender: WebContents,
+ frame: Electron.WebFrameMain | null,
+ token: unknown,
+ ): Member | null {
+ if (this.closed || token !== this.token) return null;
+ const member = this.members.get(sender.id);
+ if (!member || member.overlay.window.isDestroyed()) return null;
+ if (!frame || frame !== sender.mainFrame) return null;
+ return member;
+ }
+
+ owns(overlay: OverlayWindow): boolean {
+ return [...this.members.values()].some((m) => m.overlay === overlay);
+ }
+
+ painted(sender: WebContents, frame: Electron.WebFrameMain | null, token: unknown): void {
+ const member = this.member(sender, frame, token);
+ if (!member) return;
+ member.painted = true;
+ if (this.live?.editing && this.live.member === member) {
+ member.overlay.window.setOpacity(1);
+ member.overlay.window.focus();
+ return;
+ }
+ if ([...this.members.values()].every((m) => m.painted)) this.reveal();
+ }
+
+ focused(sender: WebContents, frame: Electron.WebFrameMain | null, token: unknown): void {
+ if (!this.member(sender, frame, token)) return;
+ }
+
+ selectionStarted(sender: WebContents, frame: Electron.WebFrameMain | null, token: unknown): void {
+ const member = this.member(sender, frame, token);
+ if (!member) return;
+ // 一次只截一块屏: 在这块屏开始框选时清掉其它屏上的选区。
+ for (const other of this.members.values()) {
+ if (other !== member && !other.overlay.window.isDestroyed()) {
+ other.overlay.window.webContents.send(REGION_SCREENSHOT_CHANNEL.CLEAR);
+ }
+ }
+ }
+
+ async elementsAt(
+ sender: WebContents,
+ frame: Electron.WebFrameMain | null,
+ token: unknown,
+ windowId: unknown,
+ x: unknown,
+ y: unknown,
+ ): Promise<RegionRect[]> {
+ const member = this.member(sender, frame, token);
+ if (!member || !Number.isInteger(windowId)) return [];
+ if (typeof x !== 'number' || typeof y !== 'number' || !Number.isFinite(x + y)) return [];
+ const window = this.deps.windows[windowId as number];
+ if (!window) return [];
+ const { display } = member.capture;
+ const global = { x: x + display.bounds.x, y: y + display.bounds.y };
+ const point = process.platform === 'win32' ? screen.dipToScreenPoint(global) : global;
+ const rects = await this.deps.helper.elements(window, point.x, point.y);
+ if (this.closed) return [];
+ return rects.map((rect) => toLocal(toGlobalDip(rect), display));
+ }
+
+ copyText(
+ sender: WebContents,
+ frame: Electron.WebFrameMain | null,
+ token: unknown,
+ text: unknown,
+ ) {
+ if (!this.member(sender, frame, token)) return;
+ if (typeof text !== 'string' || text.length === 0 || text.length > MAX_COLOR_TEXT) return;
+ clipboard.writeText(text);
+ }
+
+ cancel(sender: WebContents, frame: Electron.WebFrameMain | null, token: unknown): void {
+ if (this.member(sender, frame, token)) this.close();
+ }
+
+ startLive(sender: WebContents, frame: Electron.WebFrameMain | null, token: unknown, mode: unknown, rawSelection: unknown): RegionCaptureBegin | null {
+ const member = this.member(sender, frame, token);
+ if (!member || this.live || this.exporting || typeof mode !== 'string' || !['scroll', 'video', 'gif'].includes(mode)) return null;
+ const { display, image } = member.capture;
+ const selection = normalizeRegionSelection(rawSelection, display.bounds, display.scaleFactor);
+ if (!selection || selection.width < 32 || selection.height < 32) return null;
+ const area = this.chromeArea(display);
+ const layout = mode === 'scroll' ? scrollCaptureLayout(selection, display.bounds, area) : null;
+ const controls = mode === 'scroll' ? null : recordingControlsBounds(selection, display.bounds, false, undefined, area);
+ if (!layout && !controls) return null;
+ const size = image.getSize();
+ const mapping = regionSelectionToImageCrop(selection, display.bounds, size, display.scaleFactor);
+ if (!mapping) return null;
+ const crop = image.crop(mapping.crop).resize(mapping.output);
+ const croppedSize = crop.getSize();
+ if (croppedSize.width * croppedSize.height > 32_000_000) return null;
+ const center = { x: display.bounds.x + selection.x + selection.width / 2, y: display.bounds.y + selection.y + selection.height / 2 };
+ const physical = process.platform === 'win32' ? screen.dipToScreenPoint(center) : center;
+ const target = this.deps.windows.find(({ rect }) => physical.x >= rect[0] && physical.x < rect[2] && physical.y >= rect[1] && physical.y < rect[3]) ?? null;
+ this.live = { member, selection, mode: mode as RegionCaptureMode, sampling: false, lastSample: 0, editing: false, layout, automatic: false, target, ignoring: false, previewHeight: layout ? Math.min(layout.preview.height, Math.ceil(croppedSize.height * layout.preview.width / croppedSize.width)) : 0 };
+ for (const other of this.members.values()) {
+ if (other === member) continue;
+ hideScreenshotOverlay(other.overlay.window);
+ }
+ this.recordingControls = controls;
+ // Keep the visible panel's geometry and stacking unchanged. On macOS blur()
+ // orders it out and back, causing a full-screen flash at the live handoff.
+ // The nonactivating panel already leaves the captured app in the foreground;
+ // hit-testing below returns pointer input outside the controls to that app.
+ if (process.platform !== 'darwin') member.overlay.window.blur();
+ this.updateScrollHitTest();
+ this.scrollPointerTimer = setInterval(() => this.updateScrollHitTest(), 30);
+ return { mode: mode as RegionCaptureMode, selection, first: { ...croppedSize, data: new Uint8Array(crop.toBitmap()) }, ...(layout ? { scrollLayout: layout } : {}), ...(controls ? { recordingLayout: { viewport: display.bounds, controls, area } } : {}) };
+ }
+
+ updateRecordingControls(sender: WebContents, frame: Electron.WebFrameMain | null, token: unknown, expanded: unknown, point: unknown, dragging: unknown): RegionRect | null {
+ const member = this.member(sender, frame, token), live = this.live;
+ if (!member || !live || live.member !== member || live.mode === 'scroll' || typeof expanded !== 'boolean' || typeof dragging !== 'boolean') return null;
+ let position: { x: number; y: number } | undefined;
+ if (point !== undefined) {
+ if (!point || typeof point !== 'object') return null;
+ const { x, y } = point as Record<string, unknown>;
+ if (typeof x !== 'number' || typeof y !== 'number' || !Number.isFinite(x) || !Number.isFinite(y)) return null;
+ position = { x, y };
+ }
+ const { display } = member.capture;
+ const controls = recordingControlsBounds(live.selection, display.bounds, expanded, position, this.chromeArea(display));
+ if (!controls) return null;
+ this.recordingControls = controls;
+ this.draggingControls = dragging;
+ this.updateScrollHitTest();
+ return controls;
+ }
+
+ previewRecording(sender: WebContents, frame: Electron.WebFrameMain | null, token: unknown, bytes: unknown, format: unknown): boolean {
+ const member = this.member(sender, frame, token), live = this.live;
+ if (!member || !live || live.member !== member || this.exporting || live.mode === 'scroll') return false;
+ const expected = live.mode === 'gif' ? 'gif' : 'webm';
+ if (format !== expected || !validRecordingBytes(bytes, format)) return false;
+ if (!this.deps.openRecording?.(new Uint8Array(bytes), expected, member.capture.display)) return false;
+ this.handedToEditor = true;
+ this.close();
+ return true;
+ }
+
+ private updateScrollHitTest(): void {
+ const live = this.live;
+ if (!live || (!live.layout && !this.recordingControls) || live.editing || live.sampling || this.closed) return;
+ const point = screen.getCursorScreenPoint();
+ const { bounds } = live.member.capture.display;
+ const x = point.x - bounds.x, y = point.y - bounds.y;
+ const areas = live.layout ? [scrollPreviewBounds(live.layout, live.previewHeight), live.layout.auto, live.layout.actions] : [this.recordingControls!];
+ const interactive = this.draggingControls || areas.some((r) => x >= r.x && x < r.x + r.width && y >= r.y && y < r.y + r.height);
+ if (live.ignoring === !interactive) return;
+ live.ignoring = !interactive;
+ live.member.overlay.window.setIgnoreMouseEvents(!interactive, { forward: true });
+ }
+
+ /** `'accessibility'`: macOS 未授权辅助功能, 已弹出系统询问 (可直接打开系统设置)。 */
+ autoScroll(sender: WebContents, frame: Electron.WebFrameMain | null, token: unknown, enabled: unknown): boolean | 'accessibility' {
+ const member = this.member(sender, frame, token);
+ const live = this.live;
+ if (!member || !live || live.member !== member || live.mode !== 'scroll' || live.editing || this.exporting || typeof enabled !== 'boolean') return false;
+ if (enabled && !live.target) return false;
+ // 自动滚动向源应用投递滚轮事件, macOS 需要辅助功能权限; 没有时说明原因而不是静默失败。
+ if (enabled && process.platform === 'darwin' && !systemPreferences.isTrustedAccessibilityClient(false)) {
+ systemPreferences.isTrustedAccessibilityClient(true);
+ return 'accessibility';
+ }
+ live.automatic = enabled;
+ return true;
+ }
+
+ private stopScrolling(): void {
+ if (this.scrollPointerTimer) clearInterval(this.scrollPointerTimer);
+ this.scrollPointerTimer = null;
+ if (this.live) {
+ this.live.automatic = false;
+ if (!this.live.member.overlay.window.isDestroyed()) this.live.member.overlay.window.setIgnoreMouseEvents(false);
+ }
+ }
+
+ async liveFrame(sender: WebContents, frame: Electron.WebFrameMain | null, token: unknown, showKeys: unknown, previewHeight?: unknown): Promise<RegionCaptureFrame | null> {
+ const member = this.member(sender, frame, token);
+ const live = this.live;
+ if (!member || !live || live.member !== member || live.editing || live.sampling || this.exporting || Date.now() - live.lastSample < 80) return null;
+ // The visual preview grows with the image; only its visible bounds take input.
+ if (live.layout && typeof previewHeight === 'number' && Number.isFinite(previewHeight)) live.previewHeight = Math.max(1, Math.min(live.layout.preview.height, Math.ceil(previewHeight)));
+ live.sampling = true;
+ live.lastSample = Date.now();
+ try {
+ const [image, keys] = await Promise.all([
+ live.mode === 'scroll'
+ ? captureLiveRegion(member.capture.display, live.selection, live.mode, this.deps.helper)
+ : (this.videoCapture ??= new RegionVideoCapture(this.deps.helper)).frame(member.capture.display, live.selection, live.mode),
+ showKeys === true && live.mode !== 'scroll' ? this.deps.helper.keys() : Promise.resolve([]),
+ ]);
+ if (this.closed || this.live !== live || live.editing) return null;
+ if (live.automatic && live.target) {
+ const { display } = member.capture;
+ const center = { x: display.bounds.x + live.selection.x + live.selection.width / 2, y: display.bounds.y + live.selection.y + live.selection.height / 2 };
+ const point = process.platform === 'win32' ? screen.dipToScreenPoint(center) : center;
+ // Let native hit-testing see the source, including when Stop is hovered.
+ member.overlay.window.setIgnoreMouseEvents(true, { forward: true });
+ live.ignoring = true;
+ const ok = await this.deps.helper.scroll(live.target, Math.round(point.x), Math.round(point.y), -Math.max(1, Math.min(120, Math.floor(live.selection.height / 5))));
+ if (this.closed || this.live !== live || live.editing) return null;
+ if (!ok) live.automatic = false;
+ this.updateScrollHitTest();
+ }
+ const point = screen.getCursorScreenPoint();
+ const x = point.x - member.capture.display.bounds.x - live.selection.x;
+ const y = point.y - member.capture.display.bounds.y - live.selection.y;
+ return { image, keys, autoScrolling: live.automatic, cursor: x >= 0 && y >= 0 && x < live.selection.width && y < live.selection.height ? { x: x * image.width / live.selection.width, y: y * image.height / live.selection.height } : null };
+ } catch {
+ throwIpcError('INTERNAL', 'Screen capture failed');
+ } finally { live.sampling = false; this.updateScrollHitTest(); }
+ }
+
+ restoreEditor(sender: WebContents, frame: Electron.WebFrameMain | null, token: unknown, rawImage: unknown): boolean {
+ const member = this.member(sender, frame, token);
+ if (!member || !this.live || this.live.member !== member || this.live.mode !== 'scroll' || this.live.editing || this.exporting) return false;
+ const image = validateRegionBitmap(rawImage, {
+ width: Math.ceil(this.live.selection.width * member.capture.display.scaleFactor) + 2,
+ height: 32768,
+ });
+ if (!image || image.width * image.height > 32_000_000) return false;
+ if (!this.deps.openEditor?.(image, member.capture.display, this.live.selection)) return false;
+ this.handedToEditor = true;
+ this.close();
+ return true;
+ }
+
+ holdCapture(sender: WebContents, frame: Electron.WebFrameMain | null, token: unknown): void {
+ const member = this.member(sender, frame, token);
+ if (member && this.live?.member === member) {
+ this.live.automatic = false;
+ this.videoCapture?.stop();
+ }
+ }
+
+ async saveRecording(sender: WebContents, frame: Electron.WebFrameMain | null, token: unknown, bytes: unknown, format: unknown): Promise<boolean> {
+ const member = this.member(sender, frame, token);
+ if (!member || !this.live || this.live.member !== member || this.exporting) return false;
+ const expected = this.live.mode === 'gif' ? 'gif' : this.live.mode === 'video' ? 'webm' : null;
+ if (!expected || format !== expected || !validRecordingBytes(bytes, format)) return false;
+ this.exporting = true;
+ // Let the native save dialog own Escape; cancelling it must retain the finished clip.
+ this.releaseEscape();
+ try { return await saveRegionRecording(bytes, expected); }
+ finally { this.exporting = false; this.holdEscape(); }
+ }
+
+ /** 浮层页面丢了会话状态 (重新加载 / 重新挂载): 不再能正常交互, 直接结束整次截图。 */
+ abandon(sender: WebContents, frame: Electron.WebFrameMain | null): void {
+ if (this.closed || !frame || frame !== sender.mainFrame) return;
+ if (!this.members.has(sender.id)) return;
+ log.warn('overlay lost its session state, closing screenshot');
+ this.close();
+ }
+
+ /** 校验页面导出的最终图, 结束会话后交给调用方执行动作。非法 payload 返回 false。 */
+ export(
+ sender: WebContents,
+ frame: Electron.WebFrameMain | null,
+ token: unknown,
+ raw: unknown,
+ ): boolean {
+ const member = this.member(sender, frame, token);
+ if (!member || this.exporting || !raw || typeof raw !== 'object') return false;
+ const { action, selection: rawSelection, image: rawImage } = raw as Record<string, unknown>;
+ if (!isRegionScreenshotAction(action)) return false;
+ const { display } = member.capture;
+ const { width, height } = display.bounds;
+ const selection = normalizeRegionSelection(
+ rawSelection,
+ { width, height },
+ display.scaleFactor,
+ );
+ if (!selection) return false;
+ // 导出图是选区的物理像素; 混合 DPI 下定格图可能比物理分辨率大, 上限取两者较大值。
+ const frameSize = member.capture.image.getSize();
+ const limit = {
+ width: Math.ceil(Math.max(width * display.scaleFactor, frameSize.width)) + 2,
+ height: Math.ceil(Math.max(height * display.scaleFactor, frameSize.height)) + 2,
+ };
+ const isLong = this.live?.mode === 'scroll' && this.live.member === member;
+ const bitmap = validateRegionBitmap(rawImage, isLong ? { width: limit.width, height: 32768 } : limit);
+ if (!bitmap) return false;
+ if (bitmap.width * bitmap.height > 32_000_000) return false;
+ const image = nativeImage.createFromBitmap(
+ Buffer.from(bitmap.data.buffer, bitmap.data.byteOffset, bitmap.data.byteLength),
+ // 此对象保存物理像素。窗口 DIP 尺寸由 selection 独立携带,不能把图片再标成
+ // 2x 表示,否则 getSize() 与 toBitmap() 的尺寸不一致,贴图会构造失败。
+ { width: bitmap.width, height: bitmap.height, scaleFactor: 1 },
+ );
+ if (image.isEmpty()) return false;
+ this.exporting = true;
+ log.info('screenshot exported', { action, width: bitmap.width, height: bitmap.height });
+ this.close();
+ this.deps.onResult({ action, image, display, selection });
+ return true;
+ }
+
+ private reveal(): void {
+ if (this.closed) return;
+ if (this.revealTimer) {
+ clearTimeout(this.revealTimer);
+ this.revealTimer = null;
+ }
+ // 超时仍未绘制定格画面的屏不能显示 (只会是一整块黑屏, 还可能收不到按键):
+ // 隐藏这块屏的浮层; 一块都没画好就直接结束截图。
+ for (const [id, member] of [...this.members]) {
+ if (member.painted) continue;
+ log.warn('overlay did not paint in time; hiding it', {
+ displayId: member.capture.display.id,
+ });
+ if (!member.overlay.window.isDestroyed()) {
+ member.overlay.window.webContents.send(REGION_SCREENSHOT_CHANNEL.END);
+ }
+ this.deps.pool.retire(member.overlay);
+ this.members.delete(id);
+ }
+ if (this.members.size === 0) {
+ this.close();
+ return;
+ }
+ const cursor = screen.getCursorScreenPoint();
+ let target: Member | null = null;
+ for (const member of this.members.values()) {
+ const { window } = member.overlay;
+ if (window.isDestroyed()) continue;
+ window.setOpacity(1);
+ const { bounds } = member.capture.display;
+ if (
+ cursor.x >= bounds.x &&
+ cursor.x < bounds.x + bounds.width &&
+ cursor.y >= bounds.y &&
+ cursor.y < bounds.y + bounds.height
+ ) {
+ target = member;
+ }
+ }
+ // 光标所在屏的浮层拿键盘焦点 (标注文字、快捷键都要)。macOS 浮层是不激活应用的
+ // 面板: 截图前的应用保持前台, 菜单栏不切换, 滚动截图时触控板滚动照常交给它。
+ const window = (target ?? [...this.members.values()][0])?.overlay.window;
+ if (!window || window.isDestroyed()) return;
+ window.focus();
+ }
+
+ private releaseEscape(): void {
+ this.releaseEscapeShortcut?.();
+ this.releaseEscapeShortcut = null;
+ }
+
+ close(): void {
+ if (this.closed) return;
+ this.closed = true;
+ this.stopScrolling();
+ this.videoCapture?.stop();
+ this.videoCapture = null;
+ this.live = null;
+ if (this.revealTimer) clearTimeout(this.revealTimer);
+ this.releaseEscape();
+ screen.removeListener('display-added', this.onDisplaysChanged);
+ screen.removeListener('display-removed', this.onDisplaysChanged);
+ screen.removeListener('display-metrics-changed', this.onDisplayMetricsChanged);
+ for (const { overlay } of this.members.values()) {
+ const { window } = overlay;
+ if (!window.isDestroyed()) window.webContents.send(REGION_SCREENSHOT_CHANNEL.END);
+ this.deps.pool.retire(overlay);
+ }
+ this.members.clear();
+ this.deps.onClosed();
+ }
+}
diff --git a/apps/desktop/src/main/region-screenshot/snapshotHost.ts b/apps/desktop/src/main/region-screenshot/snapshotHost.ts
new file mode 100644
index 0000000000..e8fcddba7c
--- /dev/null
+++ b/apps/desktop/src/main/region-screenshot/snapshotHost.ts
@@ -0,0 +1,306 @@
+import { app } from 'electron';
+import { execFile, spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { createInterface } from 'node:readline';
+import { promisify } from 'node:util';
+
+import { createLogger } from '../logger';
+import type { RegionRect, RegionScreenshotBitmap } from '../../shared/regionScreenshot';
+
+/**
+ * 框选截图的窗口 / 界面元素识别程序 (native/region-screenshot)。
+ *
+ * 一次截图起一个进程, 会话结束即退出: 定格时取一次窗口列表, 悬停时按需查指针下
+ * 的界面元素。默认只回几何信息 (和 macOS 的进程号), 不读窗口标题或内容。
+ * 录制时用户开启「显示按键」后才按帧查询当前按下的物理按键;不读输入框、不存历史,
+ * 结束或暂停录制后不再查询。macOS 未授权输入监控时返回不可用,不自行请求权限。
+ * Windows 录制只读取 main 已校验的选区像素,留在当前用户会话;不启动提权服务。
+ * 打包版随包分发; 源码模式按源码指纹编译一次缓存到 userData。找不到、编译失败、
+ * 超时或崩溃一律降级为「不吸附」, 截图本身不受影响。
+ */
+
+const log = createLogger('region-screenshot:snapshot');
+const exec = promisify(execFile);
+const REQUEST_TIMEOUT_MS = 600;
+
+export interface SnapshotWindow {
+ /** Windows: HWND; macOS: CGWindowID。只在本次会话内使用。 */
+ handle: number;
+ pid: number | null;
+ /** Windows 为物理像素, macOS 为全局 DIP; [left, top, right, bottom]。 */
+ rect: [number, number, number, number];
+}
+
+const binaryName =
+ process.platform === 'darwin'
+ ? 'cindy-macos-screenshot-snapshot'
+ : 'cindy-windows-screenshot-snapshot.exe';
+
+let devBuild: Promise<string | null> | null = null;
+let devBinary: string | null = null;
+
+function cargoCommand(): string {
+ const candidate = path.join(os.homedir(), '.cargo', 'bin', 'cargo.exe');
+ return candidate;
+}
+
+async function buildFromSource(): Promise<string | null> {
+ const root = path.join(app.getAppPath(), 'native', 'region-screenshot');
+ const files =
+ process.platform === 'darwin'
+ ? [path.join(root, 'macos-snapshot.swift')]
+ : ['src/main.rs', 'Cargo.toml', 'Cargo.lock'].map((f) =>
+ path.join(root, 'windows-snapshot', f),
+ );
+ const digest = createHash('sha256').update(process.arch).update('v1');
+ for (const file of files) digest.update(await fs.readFile(file));
+ const directory = path.join(
+ app.getPath('userData'),
+ 'region-screenshot',
+ 'native',
+ digest.digest('hex'),
+ );
+ const binary = path.join(directory, binaryName);
+ try {
+ await fs.access(binary);
+ return binary;
+ } catch {
+ /* build this source version */
+ }
+ await fs.mkdir(directory, { recursive: true });
+ const temporary = `${binary}.${process.pid}.tmp`;
+ if (process.platform === 'darwin') {
+ await exec('swiftc', [files[0], '-O', '-o', temporary], { timeout: 180_000 });
+ } else {
+ let cargo = cargoCommand();
+ try {
+ await fs.access(cargo);
+ } catch {
+ cargo = 'cargo';
+ }
+ await exec(
+ cargo,
+ [
+ 'build',
+ '--release',
+ '--locked',
+ '--manifest-path',
+ path.join(root, 'windows-snapshot', 'Cargo.toml'),
+ '--target-dir',
+ path.join(directory, 'build'),
+ ],
+ { timeout: 300_000, windowsHide: true },
+ );
+ await fs.copyFile(path.join(directory, 'build', 'release', binaryName), temporary);
+ }
+ await fs.rename(temporary, binary);
+ return binary;
+}
+
+/** 识别程序路径; 不支持的平台或源码模式编译失败返回 null (只尝试一次)。 */
+export function resolveSnapshotBinary(waitForBuild = true): Promise<string | null> {
+ if (process.platform !== 'win32' && process.platform !== 'darwin') return Promise.resolve(null);
+ if (app.isPackaged) {
+ return Promise.resolve(
+ path.join(process.resourcesPath, 'tools', 'region-screenshot', binaryName),
+ );
+ }
+ devBuild ??= buildFromSource()
+ .then((binary) => {
+ devBinary = binary;
+ return binary;
+ })
+ .catch((error: unknown) => {
+ log.warn('snapshot helper build failed; snapping disabled in this run', { error });
+ return null;
+ });
+ return waitForBuild ? devBuild : Promise.resolve(devBinary);
+}
+
+interface Pending {
+ resolve: (value: Record<string, unknown> | null) => void;
+ timer: ReturnType<typeof setTimeout>;
+}
+
+/** 一次截图会话内的识别程序进程。所有请求失败都返回空结果, 不抛错。 */
+export class SnapshotHelper {
+ /** One bounded wheel step in the captured window; never an arbitrary input bridge. */
+ async scroll(window: SnapshotWindow, x: number, y: number, delta: number): Promise<boolean> {
+ const response = await this.request({ op: 'scroll', hwnd: window.handle, pid: window.pid, x, y, delta });
+ return response?.ok === true;
+ }
+ private child: ChildProcessWithoutNullStreams | null = null;
+ private nextId = 1;
+ private readonly pending = new Map<number, Pending>();
+
+ static async start(waitForBuild = true): Promise<SnapshotHelper> {
+ const helper = new SnapshotHelper();
+ const binary = await resolveSnapshotBinary(waitForBuild);
+ if (binary) helper.spawn(binary);
+ return helper;
+ }
+
+ private spawn(binary: string): void {
+ try {
+ const child = spawn(binary, [], { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+ this.child = child;
+ const fail = (error: Error) => {
+ if (this.child !== child) return;
+ log.warn('snapshot helper failed to run', { error });
+ this.dispose();
+ };
+ child.on('error', fail);
+ // 流的 error 不会转发成 ChildProcess.error; 保留监听器接住关闭后的迟到错误。
+ child.stdin.on('error', fail);
+ child.stdout.on('error', fail);
+ child.stderr.on('error', fail);
+ child.on('exit', () => {
+ if (this.child === child) this.dispose();
+ });
+ child.stderr.resume();
+ createInterface({ input: child.stdout })
+ .on('error', fail)
+ .on('line', (line) => this.onLine(line));
+ } catch (error) {
+ log.warn('snapshot helper spawn threw', { error });
+ this.child = null;
+ }
+ }
+
+ private onLine(line: string): void {
+ let message: Record<string, unknown>;
+ try {
+ const parsed: unknown = JSON.parse(line);
+ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return;
+ message = parsed as Record<string, unknown>;
+ } catch {
+ return;
+ }
+ const id = typeof message.id === 'number' ? message.id : NaN;
+ const entry = this.pending.get(id);
+ if (!entry) return;
+ this.pending.delete(id);
+ clearTimeout(entry.timer);
+ entry.resolve(message);
+ }
+
+ private request(payload: Record<string, unknown>, timeoutMs = REQUEST_TIMEOUT_MS) {
+ const child = this.child;
+ if (!child || !child.stdin.writable) return Promise.resolve(null);
+ const id = this.nextId++;
+ return new Promise<Record<string, unknown> | null>((resolve) => {
+ const timer = setTimeout(() => {
+ // 顺序协议不能取消 native 当前调用; 超时后结束本次 helper,避免旧查询排队。
+ this.dispose();
+ }, timeoutMs);
+ this.pending.set(id, { resolve, timer });
+ try {
+ child.stdin.write(`${JSON.stringify({ ...payload, id })}\n`, (error) => {
+ if (error && this.child === child) this.dispose();
+ });
+ } catch {
+ this.dispose();
+ }
+ });
+ }
+
+ async windows(): Promise<SnapshotWindow[]> {
+ const response = await this.request({ op: 'windows' }, 1500);
+ const list = Array.isArray(response?.windows) ? response.windows : [];
+ const windows: SnapshotWindow[] = [];
+ for (const raw of list) {
+ if (!raw || typeof raw !== 'object') continue;
+ const { hwnd, pid, rect } = raw as Record<string, unknown>;
+ if (typeof hwnd !== 'number' || !isRectTuple(rect)) continue;
+ windows.push({ handle: hwnd, pid: typeof pid === 'number' ? pid : null, rect });
+ }
+ return windows;
+ }
+
+ /** 指针下的界面元素 (由内到外), 坐标系同 {@link SnapshotWindow.rect}。 */
+ async elements(window: SnapshotWindow, x: number, y: number): Promise<SnapshotWindow['rect'][]> {
+ const response = await this.request({
+ op: 'elements',
+ hwnd: window.handle,
+ ...(window.pid !== null ? { pid: window.pid } : {}),
+ x: Math.round(x),
+ y: Math.round(y),
+ });
+ const rects = Array.isArray(response?.rects) ? response.rects : [];
+ return rects.filter(isRectTuple);
+ }
+
+ /** macOS: 截图前的前台应用进程号, 结束后把焦点还给它。 */
+ async frontmostPid(): Promise<number | null> {
+ if (process.platform !== 'darwin') return null;
+ const response = await this.request({ op: 'frontmost' });
+ return typeof response?.pid === 'number' ? response.pid : null;
+ }
+
+ async activate(pid: number): Promise<void> {
+ if (process.platform !== 'darwin') return;
+ await this.request({ op: 'activate', pid });
+ }
+
+ /** Only requested while the user explicitly enabled key display during recording. Never logged. */
+ async keys(): Promise<string[] | null> {
+ const response = await this.request({ op: 'keys' });
+ if (!Array.isArray(response?.keys)) return null;
+ return response.keys.filter((value): value is string => typeof value === 'string' && value.length <= 16).slice(0, 8);
+ }
+
+ /** macOS: 每块显示器 (按 Display.id) 顶部被摄像头刘海占用的高度 (DIP)。 */
+ async screenInsets(): Promise<Map<number, number>> {
+ const insets = new Map<number, number>();
+ if (process.platform !== 'darwin') return insets;
+ const response = await this.request({ op: 'screens' });
+ for (const raw of Array.isArray(response?.screens) ? response.screens : []) {
+ const { id, top } = (raw ?? {}) as Record<string, unknown>;
+ if (Number.isInteger(id) && typeof top === 'number' && top >= 0 && top < 200) insets.set(id as number, top);
+ }
+ return insets;
+ }
+
+ /** Windows capture in the current user session; no elevated desktop broker. */
+ async capture(rect: RegionRect, edge: number): Promise<RegionScreenshotBitmap | null> {
+ const response = await this.request({ op: 'frame', ...rect, edge }, 1500);
+ if (!response || typeof response.pixels !== 'string') return null;
+ const { width, height } = response;
+ if (typeof width !== 'number' || typeof height !== 'number' || !Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0 || width > edge || height > edge || width * height > 32_000_000) return null;
+ if (response.pixels.length > Math.ceil(width * height * 4 / 3) * 4) return null;
+ const bytes = Buffer.from(response.pixels, 'base64');
+ if (bytes.length !== width * height * 4) return null;
+ return { width, height, data: new Uint8Array(bytes) };
+ }
+
+ dispose(): void {
+ const child = this.child;
+ this.child = null;
+ for (const entry of this.pending.values()) {
+ clearTimeout(entry.timer);
+ entry.resolve(null);
+ }
+ this.pending.clear();
+ if (child && child.exitCode === null) {
+ child.stdin.destroy();
+ try {
+ child.kill();
+ } catch {
+ /* already gone */
+ }
+ }
+ }
+}
+
+function isRectTuple(value: unknown): value is [number, number, number, number] {
+ return (
+ Array.isArray(value) &&
+ value.length === 4 &&
+ value.every((v) => typeof v === 'number' && Number.isFinite(v)) &&
+ value[2] > value[0] &&
+ value[3] > value[1]
+ );
+}
diff --git a/apps/desktop/src/main/remote-desktop/__tests__/captureWindow.test.ts b/apps/desktop/src/main/remote-desktop/__tests__/captureWindow.test.ts
index c7e4cdf563..f8cd927735 100644
--- a/apps/desktop/src/main/remote-desktop/__tests__/captureWindow.test.ts
+++ b/apps/desktop/src/main/remote-desktop/__tests__/captureWindow.test.ts
@@ -1,7 +1,7 @@
import { EventEmitter } from 'node:events';
import { afterEach, beforeEach, expect, it, vi } from 'vitest';
import { DesktopCaptureWindow } from '../captureWindow';
-import { denyAppDesktopCapture } from '../capturePermissions';
+import { denyAppDesktopCapture, markPlaybackFullscreenWindow } from '../capturePermissions';
import { buildContentSecurityPolicy } from '../../security/csp';
const fake = vi.hoisted(() => ({
@@ -222,6 +222,43 @@ it('denies app display/legacy capture while preserving physical microphone and c
expect(reply).toHaveBeenLastCalledWith({});
});
+// User regression: the recording preview's native fullscreen button did nothing.
+// Existing permission cases only cover app/voice owners, not playback-only windows.
+// Minimal input: registered preview top frame requests fullscreen; both production
+// handlers must allow it without granting capture or trusting a foreign frame. Tier: unit.
+it('grants registered playback windows only user-initiated fullscreen', () => {
+ const ses = {
+ setDisplayMediaRequestHandler: vi.fn(),
+ setPermissionCheckHandler: vi.fn(),
+ setPermissionRequestHandler: vi.fn(),
+ };
+ const preview = { kind: 'preview', mainFrame: { url: 'file:///app/index.html' }, isDestroyed: () => false };
+ const details = { isMainFrame: true, requestingUrl: preview.mainFrame.url };
+ denyAppDesktopCapture(ses as any);
+ const check = ses.setPermissionCheckHandler.mock.calls[0][0];
+ const request = ses.setPermissionRequestHandler.mock.calls[0][0];
+ const assertPermission = (owner: unknown, permission: string, requestDetails: unknown, allowed: boolean) => {
+ expect(check(owner, permission, '', requestDetails)).toBe(allowed);
+ const reply = vi.fn();
+ request(owner, permission, reply, requestDetails);
+ expect(reply).toHaveBeenCalledWith(allowed);
+ };
+ assertPermission(preview, 'fullscreen', details, false);
+ markPlaybackFullscreenWindow(preview as any);
+ assertPermission(preview, 'fullscreen', details, true);
+ for (const permission of ['media', 'display-capture', 'clipboard-sanitized-write', 'automatic-fullscreen']) {
+ assertPermission(preview, permission, { ...details, mediaType: 'audio', mediaTypes: ['audio'] }, false);
+ }
+ assertPermission({ ...preview }, 'fullscreen', details, false);
+ assertPermission(preview, 'fullscreen', { ...details, isMainFrame: false }, false);
+ assertPermission(preview, 'fullscreen', { ...details, requestingUrl: 'https://foreign.example/' }, false);
+ preview.mainFrame.url = 'https://foreign.example/';
+ assertPermission(preview, 'fullscreen', { ...details, requestingUrl: preview.mainFrame.url }, false);
+ preview.mainFrame.url = details.requestingUrl;
+ preview.isDestroyed = () => true;
+ assertPermission(preview, 'fullscreen', details, false);
+});
+
it('capture CSP forbids arbitrary network, application frames and inline/eval scripts', () => {
const csp = buildContentSecurityPolicy({
isDev: false,
diff --git a/apps/desktop/src/main/remote-desktop/capturePermissions.ts b/apps/desktop/src/main/remote-desktop/capturePermissions.ts
index ee29a761e4..a4acb55db3 100644
--- a/apps/desktop/src/main/remote-desktop/capturePermissions.ts
+++ b/apps/desktop/src/main/remote-desktop/capturePermissions.ts
@@ -1,6 +1,14 @@
import { BrowserWindow, type Session, type WebContents } from 'electron';
import { isTrustedAppRendererWindow, isTrustedCindyRendererWindow } from '../security/trustedAppRenderer';
+const playbackFullscreenWindows = new WeakSet<BrowserWindow>();
+
+/** Playback-only windows may enter HTML fullscreen without becoming app-content
+ * windows or acquiring microphone, camera, clipboard or screen capture access. */
+export function markPlaybackFullscreenWindow(window: BrowserWindow): void {
+ playbackFullscreenWindows.add(window);
+}
+
/** Remove desktop capture from the app session, including Chromium's legacy
* chromeMediaSource path (reported as media with no physical mediaTypes).
* Keep physical media and clipboard writes confined to trusted top-level pages. */
@@ -8,15 +16,19 @@ export function denyAppDesktopCapture(
ses: Session,
isVoiceInputOwner: (owner: WebContents) => boolean = () => false,
): void {
- const trusted = (owner: WebContents | null, details: { isMainFrame: boolean; requestingUrl?: string }, allowVoiceInput: boolean) => {
+ const trusted = (owner: WebContents | null, details: { isMainFrame: boolean; requestingUrl?: string }, permission: string) => {
if (!owner || owner.isDestroyed() || !details.isMainFrame || details.requestingUrl !== owner.mainFrame.url)
return false;
const win = BrowserWindow.fromWebContents(owner);
- return isTrustedAppRendererWindow(win) || (allowVoiceInput && isVoiceInputOwner(owner) && isTrustedCindyRendererWindow(win));
+ return isTrustedAppRendererWindow(win) || (isTrustedCindyRendererWindow(win) && (
+ permission === 'fullscreen'
+ ? !!win && playbackFullscreenWindows.has(win)
+ : isVoiceInputOwner(owner)
+ ));
};
ses.setDisplayMediaRequestHandler((_request, callback) => callback({}));
ses.setPermissionCheckHandler((owner, permission, _origin, details) => {
- if (!trusted(owner, details, permission !== 'fullscreen')) return false;
+ if (!trusted(owner, details, permission)) return false;
if (permission === 'media')
return details.mediaType === 'audio' || details.mediaType === 'video';
// Native video controls use Fullscreen API permission, not display capture.
@@ -24,7 +36,7 @@ export function denyAppDesktopCapture(
return permission === 'clipboard-sanitized-write' || permission === 'fullscreen';
});
ses.setPermissionRequestHandler((owner, permission, callback, details) => {
- if (!trusted(owner, details, permission !== 'fullscreen')) return callback(false);
+ if (!trusted(owner, details, permission)) return callback(false);
if (permission === 'media') {
const types = 'mediaTypes' in details ? details.mediaTypes : undefined;
return callback(
diff --git a/apps/desktop/src/main/resource-usage-window/controller.ts b/apps/desktop/src/main/resource-usage-window/controller.ts
index 471db3ded3..ea576bc193 100644
--- a/apps/desktop/src/main/resource-usage-window/controller.ts
+++ b/apps/desktop/src/main/resource-usage-window/controller.ts
@@ -45,7 +45,10 @@ export interface ResourceUsageWindowControllerDeps {
*/
pauseWhenHidden?: boolean;
onActivityChanged?: (window: BrowserWindow, active: boolean) => void;
+ /** Runs only when a requested presentation is shown, never during hidden prewarm. */
+ onBeforeShow?: (window: BrowserWindow) => void;
onCloseRequested?: (window: BrowserWindow) => void;
+ onUnavailable?: () => void;
isOpenSender: (sender: WebContents) => boolean;
/** 打开监视器的那扇应用窗;用于跟随显隐并在关闭监视器后恢复焦点。 */
getOwnerWindow?: (sender: WebContents) => ResourceUsageOwnerWindow | null;
@@ -90,6 +93,17 @@ export class ResourceUsageWindowController {
this.ensureWindow();
}
+ /** A reused editor is about to receive a different document; wait for its first paint. */
+ resetPresentation(): void {
+ this.presentationReady = false;
+ }
+
+ /** A renderer error boundary can request the same bounded recovery as a process crash. */
+ rendererFailed(sender: WebContents): void {
+ const win = this.windowForSender(sender);
+ if (win) this.invalidateWindow(win, 'renderer reported a rendering failure');
+ }
+
/** 幂等打开:热窗口立即显示;冷窗口等待首份可展示快照,异常时才显示已挂载的 Loading 壳。 */
open(sender: WebContents): boolean {
if (this.disposed) return false;
@@ -232,6 +246,7 @@ export class ResourceUsageWindowController {
win = this.deps.createWindow();
} catch (error) {
this.resetWindowState();
+ this.deps.onUnavailable?.();
log.error('resource-usage window creation failed', {
error: error instanceof Error ? error.message : String(error),
});
@@ -320,6 +335,7 @@ export class ResourceUsageWindowController {
if (!win.isVisible()) this.enteringNativeFullscreen = false;
this.visibilityGeneration += 1;
this.setSamplingActive(win, true);
+ this.deps.onBeforeShow?.(win);
if (win.isMinimized()) win.restore();
// 打开时只负责显示和聚焦,不再按 owner 状态驱动 setFullScreen。
// macOS 沿用本窗口的原生 Space / 全屏呈现;仅关闭时显式退出全屏再隐藏。
@@ -551,6 +567,7 @@ export class ResourceUsageWindowController {
if (!reopen || this.disposed) return;
if (this.automaticRecoveryAttempts >= MAX_AUTOMATIC_RECOVERY_ATTEMPTS) {
log.error('resource-usage automatic recovery exhausted', { reason });
+ this.deps.onUnavailable?.();
return;
}
this.automaticRecoveryAttempts += 1;
diff --git a/apps/desktop/src/main/voice-input/global.ts b/apps/desktop/src/main/voice-input/global.ts
index 4d0cc5251c..ef7376a476 100644
--- a/apps/desktop/src/main/voice-input/global.ts
+++ b/apps/desktop/src/main/voice-input/global.ts
@@ -19,6 +19,7 @@ import {
import { markAppearanceSettingsReaderWindow } from '../appearance-settings-reader.js';
import { createLogger } from '../logger.js';
+import { acquireOverlayEscape } from '../overlayEscape.js';
import { scheduleMainAppPresenceRestore } from '../appPresence.js';
import { openMainWindowVoiceSettings } from '../deepLink.js';
import { throwIpcError } from '../utils/ipcValidate.js';
@@ -335,7 +336,7 @@ let registeredAccelerator: string | null = null;
let registeredShortcut: VoiceInputShortcut | null = null;
let registeredNativeShortcutLabel: string | null = null;
let registeredNativeShortcutKey: string | null = null;
-let overlayCancelRegistered = false;
+let releaseOverlayCancel: (() => void) | null = null;
let overlayWindow: BrowserWindow | null = null;
let overlayLoaded = false;
let overlayPresentationActive = false;
@@ -2208,23 +2209,21 @@ function cancelExternalDictionaryLearningWatch(): void {
}
function registerOverlayCancelShortcut(): void {
- if (overlayCancelRegistered) return;
- const ok = globalShortcut.register(OVERLAY_CANCEL_ACCELERATOR, () => {
+ if (releaseOverlayCancel) return;
+ releaseOverlayCancel = acquireOverlayEscape(() => {
const overlay = getOverlayWindow();
if (!overlay) return;
overlay.webContents.send('voice-input:global-overlay-command', { type: 'cancel' });
});
- if (!ok) {
+ if (!releaseOverlayCancel) {
log.warn('overlay cancel shortcut registration failed', { accelerator: OVERLAY_CANCEL_ACCELERATOR });
return;
}
- overlayCancelRegistered = true;
}
function unregisterOverlayCancelShortcut(): void {
- if (!overlayCancelRegistered) return;
- globalShortcut.unregister(OVERLAY_CANCEL_ACCELERATOR);
- overlayCancelRegistered = false;
+ releaseOverlayCancel?.();
+ releaseOverlayCancel = null;
}
async function showOverlayWindow(shortcutInvokedAt = Date.now()): Promise<void> {
diff --git a/apps/desktop/src/preload/preload.ts b/apps/desktop/src/preload/preload.ts
index e4b031209f..58b6d367b3 100644
--- a/apps/desktop/src/preload/preload.ts
+++ b/apps/desktop/src/preload/preload.ts
@@ -291,6 +291,10 @@ import type {
DesktopLoginActionResult,
} from '../shared/authIpc';
import { BILLING_INVOKE, type BillingRendererApi } from '../shared/billing';
+import {
+ REGION_SCREENSHOT_COMPOSE_CHANNEL,
+ type RegionScreenshotComposeRequest,
+} from '../shared/regionScreenshot';
import {
REMOTE_PRECREATED_WORKTREE_LEDGER_CHANNELS,
type PendingRemotePrecreatedWorktree,
@@ -1299,8 +1303,11 @@ contextBridge.exposeInMainWorld('electronAPI', {
// renderer 只拿 overrides + platform, 生效值合并在 renderer 侧用同一份
// shared 代码完成 —— 与 main 消费端判定不漂移。
appShortcuts: {
- getState: (): { overrides: Record<string, unknown>; platform: string } =>
- ipcRenderer.sendSync('app-shortcuts:get'),
+ getState: (): {
+ overrides: Record<string, unknown>;
+ platform: string;
+ globalFailures?: unknown;
+ } => ipcRenderer.sendSync('app-shortcuts:get'),
setOverride: (id: string, combo: unknown): Promise<{ overrides: Record<string, unknown> }> =>
ipcRenderer.invoke('app-shortcuts:set-override', id, combo),
clearOverride: (id: string): Promise<{ overrides: Record<string, unknown> }> =>
@@ -4160,6 +4167,17 @@ contextBridge.exposeInMainWorld('electronAPI', {
| null
> => ipcRenderer.invoke('deep-link:take-pending'),
+ // 全局截图交给新任务: main 入仓后唤醒, MainLayout 挂载与每次唤醒时取走一次。
+ regionScreenshotCompose: {
+ onWake: (callback: () => void): (() => void) => {
+ const listener = () => callback();
+ ipcRenderer.on(REGION_SCREENSHOT_COMPOSE_CHANNEL.WAKE, listener);
+ return () => ipcRenderer.removeListener(REGION_SCREENSHOT_COMPOSE_CHANNEL.WAKE, listener);
+ },
+ take: (): Promise<RegionScreenshotComposeRequest | null> =>
+ ipcRenderer.invoke(REGION_SCREENSHOT_COMPOSE_CHANNEL.TAKE),
+ },
+
// ── TextLightbox (text-lightbox F4/F5) ──
// Read a text file (≤ MAX_PREVIEW_MB) for the in-app preview overlay. Returns
// `reason: 'oversize'` when over the cap so the renderer can render the
diff --git a/apps/desktop/src/preload/recordingPreviewPreload.ts b/apps/desktop/src/preload/recordingPreviewPreload.ts
new file mode 100644
index 0000000000..07f90adc5a
--- /dev/null
+++ b/apps/desktop/src/preload/recordingPreviewPreload.ts
@@ -0,0 +1,15 @@
+import { contextBridge, ipcRenderer } from 'electron';
+import { RECORDING_PREVIEW_CHANNEL as C, type RecordingPreviewDocument } from '../shared/regionCapture';
+import { exposeScreenshotPageElectronApi, onPayload } from './screenshotPageBridge';
+
+exposeScreenshotPageElectronApi();
+contextBridge.exposeInMainWorld('recordingPreview', {
+ ready: () => ipcRenderer.send(C.READY), failed: () => ipcRenderer.send(C.FAILED),
+ onBegin: (callback: (document: RecordingPreviewDocument) => void) => onPayload(C.BEGIN, callback),
+ onEnd: (callback: () => void) => onPayload(C.END, callback),
+ painted: (token: string) => ipcRenderer.send(C.PAINTED, token),
+ close: (token: string) => ipcRenderer.send(C.CLOSE, token),
+ minimize: (token: string) => ipcRenderer.send(C.MINIMIZE, token),
+ save: (token: string): Promise<boolean> => ipcRenderer.invoke(C.SAVE, token),
+ copy: (token: string): Promise<boolean> => ipcRenderer.invoke(C.COPY, token),
+});
diff --git a/apps/desktop/src/preload/regionScreenshotEditorPreload.ts b/apps/desktop/src/preload/regionScreenshotEditorPreload.ts
new file mode 100644
index 0000000000..a4cc94fff6
--- /dev/null
+++ b/apps/desktop/src/preload/regionScreenshotEditorPreload.ts
@@ -0,0 +1,16 @@
+import { contextBridge, ipcRenderer } from 'electron';
+import { REGION_SCREENSHOT_EDITOR_CHANNEL as C, type RegionScreenshotBegin, type RegionScreenshotExport } from '../shared/regionScreenshot';
+import { exposeScreenshotPageElectronApi, onPayload } from './screenshotPageBridge';
+
+exposeScreenshotPageElectronApi();
+// An image editor has no screen-capture, automation or window-discovery privileges.
+contextBridge.exposeInMainWorld('regionScreenshotEditor', {
+ failed: () => ipcRenderer.send(C.FAILED),
+ shellReady: () => ipcRenderer.send(C.READY),
+ onBegin: (callback: (payload: RegionScreenshotBegin) => void) => onPayload(C.BEGIN, callback),
+ onEnd: (callback: () => void) => onPayload(C.END, callback),
+ painted: (token: string) => ipcRenderer.send(C.PAINTED, token),
+ cancel: (token: string) => ipcRenderer.send(C.CANCEL, token),
+ minimize: (token: string) => ipcRenderer.send(C.MINIMIZE, token),
+ exportImage: (token: string, payload: RegionScreenshotExport): Promise<boolean> => ipcRenderer.invoke(C.EXPORT, token, payload),
+});
diff --git a/apps/desktop/src/preload/regionScreenshotPinPreload.ts b/apps/desktop/src/preload/regionScreenshotPinPreload.ts
new file mode 100644
index 0000000000..a5bc403408
--- /dev/null
+++ b/apps/desktop/src/preload/regionScreenshotPinPreload.ts
@@ -0,0 +1,28 @@
+import { contextBridge, ipcRenderer } from 'electron';
+
+import {
+ REGION_SCREENSHOT_PIN_CHANNEL as C,
+ type RegionScreenshotPinCommand,
+ type RegionScreenshotPinInit,
+ type RegionScreenshotPinState,
+} from '../shared/regionScreenshot';
+import { exposeScreenshotPageElectronApi, onPayload } from './screenshotPageBridge';
+
+/** 贴图窗口专用 preload: 只能操作自己这张贴图 (main 按 sender 反查)。 */
+exposeScreenshotPageElectronApi();
+
+contextBridge.exposeInMainWorld('regionScreenshotPin', {
+ shellReady: (): void => ipcRenderer.send(C.SHELL_READY),
+ onInit: (callback: (payload: RegionScreenshotPinInit) => void): (() => void) =>
+ onPayload(C.INIT, callback),
+ onState: (callback: (state: RegionScreenshotPinState) => void): (() => void) =>
+ onPayload(C.STATE, callback),
+ painted: (): void => ipcRenderer.send(C.PAINTED),
+ dragStart: (): void => ipcRenderer.send(C.DRAG_START),
+ dragMove: (): void => ipcRenderer.send(C.DRAG_MOVE),
+ zoom: (steps: number, x: number, y: number): void => ipcRenderer.send(C.ZOOM, steps, x, y),
+ opacity: (steps: number): void => ipcRenderer.send(C.OPACITY, steps),
+ menu: (): void => ipcRenderer.send(C.MENU),
+ command: (command: RegionScreenshotPinCommand): void => ipcRenderer.send(C.COMMAND, command),
+ unlockHover: (hovering: boolean): void => ipcRenderer.send(C.UNLOCK_HOVER, hovering),
+});
diff --git a/apps/desktop/src/preload/regionScreenshotPreload.ts b/apps/desktop/src/preload/regionScreenshotPreload.ts
new file mode 100644
index 0000000000..fe2042e9e3
--- /dev/null
+++ b/apps/desktop/src/preload/regionScreenshotPreload.ts
@@ -0,0 +1,43 @@
+import { contextBridge, ipcRenderer } from 'electron';
+
+import {
+ REGION_SCREENSHOT_CHANNEL as C,
+ type RegionRect,
+ type RegionScreenshotBegin,
+ type RegionScreenshotExport,
+ type RegionScreenshotBitmap,
+} from '../shared/regionScreenshot';
+import { exposeScreenshotPageElectronApi, onPayload } from './screenshotPageBridge';
+import { REGION_CAPTURE_CHANNEL as LIVE, type RegionCaptureMode } from '../shared/regionCapture';
+
+/**
+ * 框选浮层专用 preload: 只暴露 shared/regionScreenshot 的固定通道。每个调用都带
+ * 会话 token, main 按 sender 与 token 双重核对, 迟到的调用对新会话无效。
+ */
+exposeScreenshotPageElectronApi();
+
+contextBridge.exposeInMainWorld('regionScreenshot', {
+ recordingControls: (token: string, expanded: boolean, point?: { x: number; y: number }, dragging = false) => ipcRenderer.invoke(LIVE.CONTROLS, token, expanded, point, dragging),
+ previewRecording: (token: string, bytes: Uint8Array, format: 'webm' | 'gif') => ipcRenderer.invoke(LIVE.PREVIEW, token, bytes, format),
+ autoScroll: (token: string, enabled: boolean) => ipcRenderer.invoke(LIVE.AUTO_SCROLL, token, enabled),
+ startLive: (token: string, mode: RegionCaptureMode, selection: RegionRect) => ipcRenderer.invoke(LIVE.START, token, mode, selection),
+ restoreEditor: (token: string, image: RegionScreenshotBitmap) => ipcRenderer.invoke(LIVE.EDIT, token, image),
+ holdCapture: (token: string) => ipcRenderer.invoke(LIVE.HOLD, token),
+ liveFrame: (token: string, keys: boolean, previewHeight?: number) => ipcRenderer.invoke(LIVE.FRAME, token, keys, previewHeight),
+ saveRecording: (token: string, bytes: Uint8Array, format: 'webm' | 'gif') => ipcRenderer.invoke(LIVE.SAVE, token, bytes, format),
+ shellReady: (): void => ipcRenderer.send(C.SHELL_READY),
+ onBegin: (callback: (payload: RegionScreenshotBegin) => void): (() => void) =>
+ onPayload(C.BEGIN, callback),
+ onEnd: (callback: () => void): (() => void) => onPayload(C.END, callback),
+ onClear: (callback: () => void): (() => void) => onPayload(C.CLEAR, callback),
+ painted: (token: string): void => ipcRenderer.send(C.PAINTED, token),
+ focused: (token: string): void => ipcRenderer.send(C.FOCUSED, token),
+ selectionStarted: (token: string): void => ipcRenderer.send(C.SELECTION_START, token),
+ copyText: (token: string, text: string): void => ipcRenderer.send(C.COPY_TEXT, token, text),
+ cancel: (token: string): void => ipcRenderer.send(C.CANCEL, token),
+ abandon: (): void => ipcRenderer.send(C.ABANDON),
+ elementsAt: (token: string, windowId: number, x: number, y: number): Promise<RegionRect[]> =>
+ ipcRenderer.invoke(C.ELEMENTS_AT, token, windowId, x, y),
+ exportImage: (token: string, payload: RegionScreenshotExport): Promise<boolean> =>
+ ipcRenderer.invoke(C.EXPORT, token, payload),
+});
diff --git a/apps/desktop/src/preload/screenshotPageBridge.ts b/apps/desktop/src/preload/screenshotPageBridge.ts
new file mode 100644
index 0000000000..ca7f7a7332
--- /dev/null
+++ b/apps/desktop/src/preload/screenshotPageBridge.ts
@@ -0,0 +1,38 @@
+import { contextBridge, ipcRenderer } from 'electron';
+
+import { createAppearanceSnapshotBridge } from './appearanceSnapshot';
+import type { LocalThemesResult } from '../shared/local-themes';
+
+/**
+ * 框选浮层与贴图窗口共用的最小 electronAPI: 只够渲染端按主窗口同一份主题、字体与
+ * 日志初始化 (见 renderer/region-screenshot-entry.tsx), 没有任何写入或特权能力。
+ */
+export function exposeScreenshotPageElectronApi(): void {
+ contextBridge.exposeInMainWorld('electronAPI', {
+ platform: process.platform,
+ logToMain: (
+ level: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal',
+ scope: string,
+ msg: string,
+ ): void => ipcRenderer.send('renderer:log', level, scope, msg),
+ appearanceSettings: createAppearanceSnapshotBridge(),
+ localThemes: {
+ listSync: (): LocalThemesResult => {
+ try {
+ return ipcRenderer.sendSync('local-themes:list-sync') as LocalThemesResult;
+ } catch (error) {
+ return { success: false, error: String(error), themes: [], diagnostics: [] };
+ }
+ },
+ },
+ // 首启亮色门需要这条线索, 否则已登录的暗色用户会看到亮色浮层。
+ authHasPersistedSessionHintSync: (): boolean =>
+ ipcRenderer.sendSync('auth:has-persisted-session-hint-sync') === true,
+ });
+}
+
+export function onPayload<T>(channel: string, callback: (payload: T) => void): () => void {
+ const listener = (_event: Electron.IpcRendererEvent, payload: T): void => callback(payload);
+ ipcRenderer.on(channel, listener);
+ return () => ipcRenderer.removeListener(channel, listener);
+}
diff --git a/apps/desktop/src/renderer/__tests__/chatInputSteerShortcut.test.ts b/apps/desktop/src/renderer/__tests__/chatInputSteerShortcut.test.ts
index 99f8d637cc..972e31e227 100644
--- a/apps/desktop/src/renderer/__tests__/chatInputSteerShortcut.test.ts
+++ b/apps/desktop/src/renderer/__tests__/chatInputSteerShortcut.test.ts
@@ -38,8 +38,8 @@ describe('ChatInput steer shortcut contract', () => {
'const enterIntent = resolveComposerEnterIntent(',
"if (\n currentState === 'listening'",
);
- expect(chatInputSource).toContain('const composerCanSubmitRef = useRef(false);');
- expect(chatInputSource).toContain('composerCanSubmitRef.current = !sendButtonDisabled;');
+ // Send readiness belongs to automatic actions, not keyboard steering.
+ // chatInputModelLoading.test.tsx exercises its gates through real ChatInput.
expect(windowKeydownBlock).toContain('showStopButtonRef.current');
expect(windowKeydownBlock).toContain('const platform = window.electronAPI?.platform;');
expect(windowKeydownBlock).toContain('isComposerEnterTarget(event.target)');
@@ -70,8 +70,8 @@ describe('ChatInput steer shortcut contract', () => {
expect(editorEnterBlock).toContain("if (enterIntent === 'native') return false;");
expect(editorEnterBlock).toContain("if (enterIntent === 'ignore')");
expect(editorEnterBlock).toContain('void voiceInputStopAndSendRef.current(enterIntent);');
- // Tiptap's document is current before React's send-button effect updates
- // composerCanSubmitRef. The resolver must not use that lagging UI mirror.
+ // Tiptap's document can change before React renders the Send state.
+ // Keyboard intent must use the live editor rather than the UI readiness ref.
expect(windowComposerCaptureBlock).not.toContain('composerCanSubmitRef.current');
expect(editorEnterBlock).not.toContain('composerCanSubmitRef.current');
});
diff --git a/apps/desktop/src/renderer/__tests__/composerActionsBus.test.ts b/apps/desktop/src/renderer/__tests__/composerActionsBus.test.ts
index fe032689ec..a77fd91735 100644
--- a/apps/desktop/src/renderer/__tests__/composerActionsBus.test.ts
+++ b/apps/desktop/src/renderer/__tests__/composerActionsBus.test.ts
@@ -1,13 +1,29 @@
// @vitest-environment jsdom
import { describe, expect, it, vi } from 'vitest';
+import { getDataOwnerGeneration, setDataOwnerGeneration } from '@/contexts/dataOwnerGeneration';
import {
insertSessionLinkIntoComposer,
+ peekComposerSubmitRequest,
+ requestComposerSubmit,
+ subscribeComposerSubmitRequest,
subscribeSessionLinkInsert,
+ takeComposerSubmitRequest,
} from '@/lib/composerActionsBus';
describe('composerActionsBus', () => {
+ // Unit: queued screenshot sends must not survive an account/runtime boundary.
+ it.each(['same-owner', 'other-owner'])('drops queued submission after %s changes generation', change => {
+ const previous = getDataOwnerGeneration();
+ try {
+ setDataOwnerGeneration('owner-a', 1);
+ requestComposerSubmit({ storageKey: 'owner-draft', attachmentUrl: 'image:private' });
+ setDataOwnerGeneration(change === 'same-owner' ? 'owner-a' : 'owner-b', 2);
+ expect(peekComposerSubmitRequest('owner-draft')).toBeNull();
+ expect(takeComposerSubmitRequest('owner-draft')).toBeNull();
+ } finally { setDataOwnerGeneration(previous.dataOwnerId, previous.generation); }
+ });
it('delivers session-link insert requests and supports unsubscribe', () => {
const handler = vi.fn();
const unsubscribe = subscribeSessionLinkInsert(handler);
@@ -23,4 +39,28 @@ describe('composerActionsBus', () => {
insertSessionLinkIntoComposer(detail);
expect(handler).toHaveBeenCalledTimes(1);
});
+
+ // 截图「翻译」等一键动作会先写草稿、再切到新任务页: 请求可能早于输入框挂载。
+ // 失效后果: 请求丢失 = 点了没反应; 取走后还能再取 = 同一张截图被发两次;
+ // 过期请求还生效 = 用户之后自己编辑的草稿被意外发出。
+ it('keeps a submit request for a composer that mounts later, sends it once, and expires it', async () => {
+ vi.useFakeTimers();
+ try {
+ requestComposerSubmit({ storageKey: 'draft-a', attachmentUrl: 'cindy-media://blobs/a.png' });
+ const handler = vi.fn();
+ const unsubscribe = subscribeComposerSubmitRequest('draft-a', handler);
+ await Promise.resolve();
+ expect(handler).toHaveBeenCalledTimes(1);
+
+ expect(takeComposerSubmitRequest('draft-a')?.attachmentUrl).toBe('cindy-media://blobs/a.png');
+ expect(takeComposerSubmitRequest('draft-a')).toBeNull();
+ unsubscribe();
+
+ requestComposerSubmit({ storageKey: 'draft-a', attachmentUrl: 'cindy-media://blobs/b.png' }, 1000);
+ vi.advanceTimersByTime(1001);
+ expect(peekComposerSubmitRequest('draft-a')).toBeNull();
+ } finally {
+ vi.useRealTimers();
+ }
+ });
});
diff --git a/apps/desktop/src/renderer/__tests__/typographyDiscipline.test.ts b/apps/desktop/src/renderer/__tests__/typographyDiscipline.test.ts
index 485c3d867a..b924ad0932 100644
--- a/apps/desktop/src/renderer/__tests__/typographyDiscipline.test.ts
+++ b/apps/desktop/src/renderer/__tests__/typographyDiscipline.test.ts
@@ -144,6 +144,12 @@ interface Exemption {
}
const EXEMPTIONS: Exemption[] = [
+ {
+ file: 'src/renderer/features/region-screenshot/LiveCapturePanel.tsx',
+ rule: 'inline-size',
+ reason: 'DESIGN.md §3: user-approved 64px recording countdown, centered in a 160px indicator; ordinary controls keep token sizes.',
+ signatures: [{ match: 'fontSize …64', expected: 1 }],
+ },
{
file: 'src/renderer/components/chat/MarkdownRenderer.tsx',
rule: 'tw-weight',
diff --git a/apps/desktop/src/renderer/components/layout/MainLayout.tsx b/apps/desktop/src/renderer/components/layout/MainLayout.tsx
index 623b25265f..e6064eb74e 100644
--- a/apps/desktop/src/renderer/components/layout/MainLayout.tsx
+++ b/apps/desktop/src/renderer/components/layout/MainLayout.tsx
@@ -131,6 +131,7 @@ import { useSessionEntryLocationCommits } from '@/features/bots/useSessionEntryL
import { islandEntryRouteState, requestIslandEntryAlertDisposal } from '@/features/bots/islandEntryAlert';
import { requestProviderShareJoin } from '@/features/provider-share/joinIntent';
import { ProviderShareGlobalHost } from '@/features/provider-share/ProviderShareGlobalHost';
+import { applyScreenshotComposeRequest } from '@/features/region-screenshot/screenshotTaskHandoff';
import { remoteProjectsStore } from '@/features/device-link/remoteProjectsStore';
import {
isAgentIslandVisibleSessionOwnedByWorkdirBrowseRoute,
@@ -827,6 +828,23 @@ export function MainLayout() {
void pullChatInvitations();
}, [handleDeepLinkPayload, pullChatInvitations]);
+ // 全局截图「问 Cindy / 翻译 / 解释 / 提取文字」: 挂载时与每次唤醒时各取一次,
+ // main 侧 take 是原子的, 两条路径不会重复处理同一张截图。
+ useEffect(() => {
+ const compose = window.electronAPI.regionScreenshotCompose;
+ if (!compose) return;
+ const pull = () => {
+ void compose
+ .take()
+ .then((request) => {
+ if (request) applyScreenshotComposeRequest(request, navigate);
+ })
+ .catch(() => undefined);
+ };
+ pull();
+ return compose.onWake(pull);
+ }, [navigate]);
+
const handleToggleSidebar = useCallback(() => {
setIsSidebarCollapsed((prev) => {
const next = !prev;
diff --git a/apps/desktop/src/renderer/components/new-chat/ChatInput.tsx b/apps/desktop/src/renderer/components/new-chat/ChatInput.tsx
index 5f17b48947..150e5bd7af 100644
--- a/apps/desktop/src/renderer/components/new-chat/ChatInput.tsx
+++ b/apps/desktop/src/renderer/components/new-chat/ChatInput.tsx
@@ -119,9 +119,12 @@ import {
} from '@/contexts/dataOwnerGeneration';
import {
insertPromptIntoEditor,
+ peekComposerSubmitRequest,
+ subscribeComposerSubmitRequest,
subscribePromptInsert,
subscribeSessionLinkInsert,
subscribeTodoReferenceInsert,
+ takeComposerSubmitRequest,
} from '@/lib/composerActionsBus';
import { resolveComposerModelSelection } from './composerModelSelection';
import type { SessionRuntimeProfileProjection, SessionRuntimePendingProjection } from '@/lib/ccAgent.types';
@@ -3465,6 +3468,7 @@ export function ChatInput({
const voiceInputStopAndSendRef = useRef<
(deliveryMode?: MessageDeliveryMode) => void | Promise<void>
>(() => {});
+ const composerSubmitRequestSendRef = useRef<(() => void | Promise<void>) | null>(null);
const voiceInputCanStopAndSendRef = useRef(false);
const composerCanSubmitRef = useRef(false);
const handleVoiceInputStartRef = useRef(handleVoiceInputStart);
@@ -6499,8 +6503,42 @@ export function ChatInput({
);
useEffect(() => {
voiceInputStopAndSendRef.current = handleClickSend;
+ composerSubmitRequestSendRef.current = handleClickSend;
}, [handleClickSend]);
+ // 别处的一键动作 (截图「翻译」等) 已把草稿写好并请求发送: 等编辑器与附件同步到位,
+ // 按普通发送键同一路径发一次; 发送中 / 语音占用时与键盘输入同锁, 稍后再试直到过期。
+ useEffect(() => {
+ if (!editor || !storageKey) return;
+ let timer: ReturnType<typeof setTimeout> | null = null;
+ const attempt = () => {
+ timer = null;
+ const request = peekComposerSubmitRequest(storageKey);
+ if (!request || editor.isDestroyed) return;
+ const ready =
+ composerCanSubmitRef.current &&
+ !!composerSubmitRequestSendRef.current &&
+ !(sessionId && hasPendingAgentSendDispatch(sessionId)) &&
+ !composerMutationLockedRef.current &&
+ !isEditorEmpty(editor) &&
+ latestAttachmentsRef.current.some((file) => file.url === request.attachmentUrl);
+ if (ready) {
+ takeComposerSubmitRequest(storageKey);
+ void composerSubmitRequestSendRef.current?.();
+ return;
+ }
+ timer = setTimeout(attempt, 100);
+ };
+ const off = subscribeComposerSubmitRequest(storageKey, () => {
+ if (timer) clearTimeout(timer);
+ attempt();
+ });
+ return () => {
+ off();
+ if (timer) clearTimeout(timer);
+ };
+ }, [editor, storageKey, sessionId]);
+
// ── Model / effort / permission / folder callbacks (unchanged) ─────
// ---------------------------------------------------------------------------
// Server-first handlers: persist to server FIRST, then update UI on success.
@@ -9153,9 +9191,11 @@ export function ChatInput({
!hasVoiceDraftText &&
!voiceBusyOnCurrentComposer,
);
+ // Automatic actions must observe the same gates as the current Send button
+ // before consuming their one-shot request, including during subscription effects.
+ composerCanSubmitRef.current = !queueEditActive && !sendButtonDisabled;
useEffect(() => {
voiceInputCanStopAndSendRef.current = !queueEditActive && !sendButtonDisabled;
- composerCanSubmitRef.current = !sendButtonDisabled;
}, [queueEditActive, sendButtonDisabled]);
const canReleaseVoiceToSend = Boolean(
!disabled && (voiceInput.isListening || canSend || hasVoiceDraftText),
diff --git a/apps/desktop/src/renderer/components/new-chat/__tests__/chatInputModelLoading.test.tsx b/apps/desktop/src/renderer/components/new-chat/__tests__/chatInputModelLoading.test.tsx
index 66910cb537..c55f855f26 100644
--- a/apps/desktop/src/renderer/components/new-chat/__tests__/chatInputModelLoading.test.tsx
+++ b/apps/desktop/src/renderer/components/new-chat/__tests__/chatInputModelLoading.test.tsx
@@ -11,6 +11,7 @@ import * as providerMemory from '@/state/providerModelMemory';
import * as draftMemory from '@/state/newMakerDraft';
import { getEffortChangeCoordinator } from '../effortChangeQueue';
import { clearDraft } from '@/lib/composerDraftStore';
+import { peekComposerSubmitRequest, requestComposerSubmit, takeComposerSubmitRequest } from '@/lib/composerActionsBus';
import { makerChatStore } from '@/lib/makerChatStore';
import {
__testing as promptRecommendations,
@@ -438,6 +439,45 @@ it.each(['button', 'Enter', 'voice'] as const)(
},
);
+// PR #7300: manual-send coverage missed automatic actions consuming a request
+// while metadata/Send is disabled. Unit through real ChatInput: one screenshot,
+// one blocked request, then enable Send; retain it and dispatch exactly once.
+it.each(['metadata', 'disabled'] as const)('retains screenshot submission until %s is ready', async gate => {
+ const key = `screenshot-wait-${gate}`;
+ const onSend = vi.fn().mockResolvedValue(true);
+ const inputProps = { ...props, sessionId: key, draftKey: key, onSend,
+ attachmentState: { ...attachments, hasAttachments: true, attachments: [{
+ id: 'shot', name: 'shot.png', path: 'clipboard://shot', ext: '.png',
+ size: 16, category: 'image' as const, url: 'image:shot', mimeType: 'image/png',
+ }] },
+ };
+ const loaded = { initialModel: 'gpt-6-astra', initialProviderId: 'openai', initialEffort: 'medium' as const };
+ const view = render(<ChatInput {...inputProps} {...(gate === 'disabled' ? loaded : {})} disabled={gate === 'disabled'} />);
+ await waitFor(() => expect(h.editor).not.toBeNull());
+ await act(async () => { h.editor!.commands.setContent('<p>Explain screenshot</p>'); });
+ vi.useFakeTimers();
+ try {
+ await act(async () => {
+ requestComposerSubmit({ storageKey: key, attachmentUrl: 'image:shot' });
+ await vi.advanceTimersByTimeAsync(300);
+ });
+ expect(onSend).not.toHaveBeenCalled();
+ expect(peekComposerSubmitRequest(key)).not.toBeNull();
+ view.rerender(<ChatInput {...inputProps} {...loaded} />);
+ await act(async () => { await vi.advanceTimersByTimeAsync(300); });
+ expect(onSend).toHaveBeenCalledTimes(1);
+ expect(onSend.mock.calls[0][0]).toBe('Explain screenshot');
+ expect(peekComposerSubmitRequest(key)).toBeNull();
+ await act(async () => { await vi.advanceTimersByTimeAsync(300); });
+ expect(onSend).toHaveBeenCalledTimes(1);
+ } finally {
+ view.unmount();
+ takeComposerSubmitRequest(key);
+ clearDraft(key);
+ vi.useRealTimers();
+ }
+});
+
it('hides a missing existing model, recovers from the effective runtime, and preserves new-draft defaults', async () => {
const onSend = vi.fn();
const view = render(<ChatInput {...props} hideRuntimeControls={false} onSend={onSend} />);
diff --git a/apps/desktop/src/renderer/components/settings/KeyboardShortcutsSection.tsx b/apps/desktop/src/renderer/components/settings/KeyboardShortcutsSection.tsx
index 7a9cc78ddf..f3adbd5f5a 100644
--- a/apps/desktop/src/renderer/components/settings/KeyboardShortcutsSection.tsx
+++ b/apps/desktop/src/renderer/components/settings/KeyboardShortcutsSection.tsx
@@ -35,6 +35,7 @@ import {
getAppShortcutDefinition,
isAppShortcutAvailableOnPlatform,
isAppShortcutComboBindable,
+ isGlobalAppShortcutComboUsable,
type AppShortcutCombo,
type AppShortcutDefinition,
type AppShortcutId,
@@ -42,6 +43,7 @@ import {
import { isSystemReservedShortcut } from '../../../shared/keyboardReserved';
import {
getAppShortcutCombos,
+ getAppShortcutGlobalFailures,
getAppShortcutOverrides,
getAppShortcutPlatform,
subscribeAppShortcuts,
@@ -114,13 +116,18 @@ export function KeyboardShortcutsSection() {
const { t } = useTranslation();
const platform = getAppShortcutPlatform();
// overrides 快照订阅: 改绑 / reset 后 main 广播 → appShortcutStore 通知 →
- // 这里重渲染。快照序列化做 useSyncExternalStore 的相等性判定。
- const overridesJson = useSyncExternalStore(subscribeAppShortcuts, () =>
- JSON.stringify(getAppShortcutOverrides()),
+ // 这里重渲染。快照序列化做 useSyncExternalStore 的相等性判定; 全局快捷键
+ // 注册失败列表同属一次广播, 一并纳入快照。
+ const snapshotJson = useSyncExternalStore(subscribeAppShortcuts, () =>
+ JSON.stringify({
+ overrides: getAppShortcutOverrides(),
+ globalFailures: getAppShortcutGlobalFailures(),
+ }),
);
- const overrides = JSON.parse(overridesJson) as Partial<
- Record<AppShortcutId, AppShortcutCombo | null>
- >;
+ const { overrides, globalFailures } = JSON.parse(snapshotJson) as {
+ overrides: Partial<Record<AppShortcutId, AppShortcutCombo | null>>;
+ globalFailures: AppShortcutId[];
+ };
const [recordingId, setRecordingId] = useState<AppShortcutId | null>(null);
const [hardwarePane, setHardwarePane] = useState<HardwarePane>('list');
const [hardwareReturnTo, setHardwareReturnTo] = useState<'list' | 'accessories'>('list');
@@ -247,6 +254,11 @@ export function KeyboardShortcutsSection() {
) {
return t('settings.shortcuts.errors.menuAccelerator');
}
+ // 全局快捷键在所有应用里截走按键: 须能注册到系统且不占编辑惯例键
+ // (与 main store 校验一致)。
+ if (selfDef.scope === 'global' && !isGlobalAppShortcutComboUsable(combo, platform)) {
+ return t('settings.shortcuts.errors.globalUnusable');
+ }
// 跨 id 冲突: 与 main store 写入兜底共用 shared 的 findAppShortcutConflict。
const conflictId = findAppShortcutConflict(id, combo, getAppShortcutOverrides(), platform);
if (conflictId) {
@@ -468,7 +480,13 @@ export function KeyboardShortcutsSection() {
const isRecording = recordingId === def.id;
const customized = def.id in overrides;
const combos = getAppShortcutCombos(def.id);
- const rowError = error?.id === def.id ? error.message : null;
+ // 写入错误优先; 否则提示全局快捷键当前未能注册 (被其它应用占用)。
+ const rowError =
+ error?.id === def.id
+ ? error.message
+ : combos.length > 0 && globalFailures.includes(def.id)
+ ? t('settings.shortcuts.errors.globalOccupied')
+ : null;
return (
<div key={def.id} className="flex items-center gap-2 py-2">
{/* 条目标题 + 说明双行: 标题主文字色 + 说明次级色,
diff --git a/apps/desktop/src/renderer/components/settings/__tests__/KeyboardShortcutsSection.accessories.test.tsx b/apps/desktop/src/renderer/components/settings/__tests__/KeyboardShortcutsSection.accessories.test.tsx
index 37ddc97321..1b67b6dd3f 100644
--- a/apps/desktop/src/renderer/components/settings/__tests__/KeyboardShortcutsSection.accessories.test.tsx
+++ b/apps/desktop/src/renderer/components/settings/__tests__/KeyboardShortcutsSection.accessories.test.tsx
@@ -47,6 +47,7 @@ vi.mock('@/lib/logger', () => ({
vi.mock('@/lib/appShortcutStore', () => ({
getAppShortcutCombos: () => [],
+ getAppShortcutGlobalFailures: () => [],
getAppShortcutOverrides: () => ({}),
getAppShortcutPlatform: () => 'darwin',
subscribeAppShortcuts: () => () => {},
diff --git a/apps/desktop/src/renderer/components/settings/__tests__/KeyboardShortcutsSection.mutationRace.test.tsx b/apps/desktop/src/renderer/components/settings/__tests__/KeyboardShortcutsSection.mutationRace.test.tsx
index 74657ae74e..8e30f0c99e 100644
--- a/apps/desktop/src/renderer/components/settings/__tests__/KeyboardShortcutsSection.mutationRace.test.tsx
+++ b/apps/desktop/src/renderer/components/settings/__tests__/KeyboardShortcutsSection.mutationRace.test.tsx
@@ -39,6 +39,7 @@ vi.mock('@/lib/logger', () => ({
vi.mock('@/lib/appShortcutStore', () => ({
getAppShortcutCombos: mocks.getCombos,
+ getAppShortcutGlobalFailures: () => [],
getAppShortcutOverrides: mocks.getOverrides,
getAppShortcutPlatform: () => 'darwin',
subscribeAppShortcuts: () => () => {},
diff --git a/apps/desktop/src/renderer/features/region-screenshot/LiveCapturePanel.tsx b/apps/desktop/src/renderer/features/region-screenshot/LiveCapturePanel.tsx
new file mode 100644
index 0000000000..f58763bd76
--- /dev/null
+++ b/apps/desktop/src/renderer/features/region-screenshot/LiveCapturePanel.tsx
@@ -0,0 +1,280 @@
+import { useEffect, useRef, useState, type PointerEvent } from 'react';
+import { useTranslation } from 'react-i18next';
+import { GripVertical, Pause, Play, Pencil, Square, X } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import { MAX_RECORDING_MS, recordingControlsBounds, type RegionCaptureBegin } from '../../../shared/regionCapture';
+import type { RegionScreenshotBitmap } from '../../../shared/regionScreenshot';
+import { bitmapToImageData, type RegionScreenshotOverlayBridge } from './bridge';
+import { CaptureRecorder } from './captureRecorder';
+import { SCREENSHOT_INK } from './screenshotColors';
+
+type Phase = 'countdown' | 'capturing' | 'paused' | 'finishing' | 'done';
+type Point = { x: number; y: number };
+type Mark = { kind: 'pen' | 'arrow' | 'rect'; points: Point[] };
+
+export function LiveCapturePanel({ begin, token, bridge }: { begin: RegionCaptureBegin; token: string; bridge: RegionScreenshotOverlayBridge }) {
+ const { t } = useTranslation();
+ const preview = useRef<HTMLCanvasElement>(null);
+ const runtime = useRef({
+ phase: 'countdown' as Phase, countdownUntil: 0,
+ active: true, inFlight: null as Promise<void> | null, recorder: null as CaptureRecorder | null,
+ canvas: null as HTMLCanvasElement | null,
+ imageData: undefined as ImageData | undefined,
+ bitmap: begin.first, marks: [] as Mark[], draft: null as Mark | null,
+ elapsed: 0, startedAt: 0,
+ });
+ const [phase, setPhase] = useState<Phase>(runtime.current.phase);
+ const [error, setError] = useState('');
+ const [status, setStatus] = useState('');
+ const [elapsed, setElapsed] = useState(0);
+ const [countdown, setCountdown] = useState(3);
+ const [expanded, setExpanded] = useState(false);
+ const layout = begin.recordingLayout!;
+ const [controls, setControls] = useState(layout.controls);
+ const drag = useRef<{ pointerId: number; x: number; y: number; left: number; top: number; point: Point } | null>(null);
+ const controlsRequest = useRef(0);
+ const [tool, setTool] = useState<Mark['kind'] | null>(null);
+ const [result, setResult] = useState<Uint8Array<ArrayBuffer> | null>(null);
+ const [saving, setSaving] = useState(false);
+ const currentTime = () => runtime.current.elapsed + (runtime.current.phase === 'capturing' ? performance.now() - runtime.current.startedAt : 0);
+ const changePhase = (next: Phase) => { runtime.current.phase = next; setPhase(next); };
+
+ function paint(bitmap: RegionScreenshotBitmap, pointer: Point | null = null) {
+ const state = runtime.current;
+ state.canvas ??= document.createElement('canvas');
+ const canvas = state.canvas;
+ if (canvas.width !== bitmap.width || canvas.height !== bitmap.height) { canvas.width = bitmap.width; canvas.height = bitmap.height; }
+ const ctx = canvas.getContext('2d', { willReadFrequently: true })!;
+ state.imageData = bitmapToImageData(bitmap, state.imageData);
+ ctx.putImageData(state.imageData, 0, 0);
+ {
+ ctx.strokeStyle = SCREENSHOT_INK.red;
+ ctx.lineWidth = Math.max(2, bitmap.width / 350);
+ ctx.lineJoin = 'round'; ctx.lineCap = 'round';
+ for (const mark of state.draft ? [...state.marks, state.draft] : state.marks) {
+ const points = mark.points.map((point) => ({ x: point.x * bitmap.width, y: point.y * bitmap.height }));
+ const first = points[0], last = points[points.length - 1];
+ if (!first || !last) continue;
+ ctx.beginPath();
+ if (mark.kind === 'rect') ctx.rect(first.x, first.y, last.x - first.x, last.y - first.y);
+ else {
+ ctx.moveTo(first.x, first.y);
+ for (const point of mark.kind === 'arrow' ? [last] : points.slice(1)) ctx.lineTo(point.x, point.y);
+ if (mark.kind === 'arrow') {
+ const angle = Math.atan2(last.y - first.y, last.x - first.x), length = ctx.lineWidth * 5;
+ for (const delta of [-0.5, 0.5]) { ctx.moveTo(last.x, last.y); ctx.lineTo(last.x - length * Math.cos(angle + delta), last.y - length * Math.sin(angle + delta)); }
+ }
+ }
+ ctx.stroke();
+ }
+ if (pointer) {
+ ctx.fillStyle = SCREENSHOT_INK.white; ctx.strokeStyle = SCREENSHOT_INK.black; ctx.lineWidth = 1.5;
+ ctx.beginPath(); ctx.moveTo(pointer.x, pointer.y); ctx.lineTo(pointer.x + 5, pointer.y + 19); ctx.lineTo(pointer.x + 9, pointer.y + 12); ctx.lineTo(pointer.x + 16, pointer.y + 11); ctx.closePath(); ctx.fill(); ctx.stroke();
+ }
+ }
+ const target = preview.current;
+ if (target) {
+ if (target.width !== bitmap.width || target.height !== bitmap.height) {
+ target.width = bitmap.width; target.height = bitmap.height;
+ }
+ target.getContext('2d')!.drawImage(canvas, 0, 0);
+ }
+ }
+
+ async function sample() {
+ const state = runtime.current;
+ const frame = await bridge.liveFrame(token, false);
+ if (!state.active || state.phase !== 'capturing' || !frame) return;
+ {
+ state.bitmap = frame.image;
+ paint(frame.image, frame.cursor);
+ if (!state.recorder) {
+ state.startedAt = performance.now(); state.elapsed = 0;
+ state.recorder = new CaptureRecorder(state.canvas!, begin.mode === 'gif' ? 'gif' : 'webm', () => { setStatus('limit'); void finish(); });
+ }
+ state.recorder.add(currentTime());
+ setElapsed(Math.floor(currentTime() / 1000) * 1000);
+ if (currentTime() >= MAX_RECORDING_MS) { setStatus('limit'); queueMicrotask(() => void finish()); }
+ }
+ }
+
+ useEffect(() => {
+ const state = runtime.current;
+ state.active = true; state.countdownUntil = performance.now() + 3000;
+ paint(begin.first);
+ let timer: ReturnType<typeof setTimeout>;
+ const tick = async () => {
+ if (!state.active) return;
+ const tickStarted = performance.now();
+ if (state.phase === 'countdown') {
+ const remaining = Math.max(0, Math.ceil((state.countdownUntil - tickStarted) / 1000));
+ setCountdown(remaining);
+ if (!remaining) {
+ state.startedAt = performance.now(); changePhase('capturing');
+ // Let the countdown leave the compositor before capturing the first frame.
+ timer = setTimeout(tick, 150);
+ return;
+ }
+ }
+ if (state.phase === 'capturing') {
+ state.inFlight = sample().catch(() => {
+ if (!state.active || state.phase !== 'capturing') return;
+ state.elapsed = currentTime();
+ state.recorder?.pause(state.elapsed);
+ changePhase('paused'); setError('captureFailed');
+ });
+ await state.inFlight;
+ state.inFlight = null;
+ }
+ if (state.active) timer = setTimeout(tick, Math.max(0, 100 - (performance.now() - tickStarted)));
+ };
+ timer = setTimeout(tick, 250);
+ return () => { state.active = false; clearTimeout(timer); state.recorder?.dispose(); };
+ // A capture's lifetime is the component's lifetime; all changing options live in runtime.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, []);
+
+ useEffect(() => { if (expanded) paint(runtime.current.bitmap); }, [expanded]);
+
+ function pause() {
+ const state = runtime.current;
+ if (state.phase === 'capturing') {
+ state.elapsed = currentTime(); state.recorder?.pause(state.elapsed); changePhase('paused'); setStatus('paused');
+ void bridge.holdCapture(token).catch(() => {});
+ } else if (state.phase === 'paused') {
+ state.startedAt = performance.now(); state.recorder?.resume(); changePhase('capturing'); setError(''); setStatus('recording');
+ }
+ }
+
+ async function finish() {
+ const state = runtime.current;
+ if (state.phase === 'done' || state.phase === 'finishing' || state.phase === 'countdown') return;
+ const at = currentTime();
+ state.elapsed = at; setElapsed(at);
+ changePhase('finishing');
+ // Finish after any in-flight sample; it will see the changed phase and discard its frame.
+ await state.inFlight;
+ if (!state.active) return;
+ try {
+ await bridge.holdCapture(token);
+ {
+ if (!state.recorder) { setError('captureFailed'); changePhase('paused'); return; }
+ const bytes = await state.recorder.finish(at);
+ if (!state.active) return;
+ setResult(bytes);
+ changePhase('done'); setStatus('done');
+ await previewRecording(bytes);
+ }
+ } catch { if (state.active) { setError('encodeFailed'); changePhase('done'); } }
+ }
+
+ async function previewRecording(bytes: Uint8Array<ArrayBuffer>) {
+ try {
+ const opened = await bridge.previewRecording(token, bytes, begin.mode === 'gif' ? 'gif' : 'webm');
+ if (!opened && runtime.current.active) setError('previewUnavailable');
+ } catch { if (runtime.current.active) setError('previewUnavailable'); }
+ }
+
+ async function saveRecording() {
+ if (!result) return;
+ setSaving(true);
+ try {
+ if (await bridge.saveRecording(token, result, begin.mode === 'gif' ? 'gif' : 'webm')) setStatus('saved');
+ } catch { setError('exportFailed'); }
+ finally { if (runtime.current.active) setSaving(false); }
+ }
+
+ function point(event: PointerEvent<HTMLCanvasElement>): Point {
+ const rect = event.currentTarget.getBoundingClientRect();
+ return { x: Math.max(0, Math.min(1, (event.clientX - rect.left) / rect.width)), y: Math.max(0, Math.min(1, (event.clientY - rect.top) / rect.height)) };
+ }
+
+ async function moveControls(nextExpanded: boolean, point?: Point, dragging = false) {
+ const next = recordingControlsBounds(begin.selection, layout.viewport, nextExpanded, point, layout.area);
+ if (!next) { setError('annotationNoRoom'); return; }
+ const request = ++controlsRequest.current;
+ setControls(next); setExpanded(nextExpanded);
+ try {
+ const accepted = await bridge.recordingControls(token, nextExpanded, point, dragging);
+ if (accepted && runtime.current.active && request === controlsRequest.current) setControls(accepted);
+ } catch { if (runtime.current.active) setError('captureFailed'); }
+ }
+
+ function dragPoint(event: PointerEvent<HTMLButtonElement>): Point | null {
+ const start = drag.current;
+ if (!start || start.pointerId !== event.pointerId) return null;
+ return { x: start.left + event.clientX - start.x, y: start.top + event.clientY - start.y };
+ }
+
+ function endDrag(event: PointerEvent<HTMLButtonElement>, finalPoint?: Point | null) {
+ const start = drag.current;
+ if (!start || start.pointerId !== event.pointerId) return;
+ drag.current = null;
+ // Use the final pointer position, not the last React render / IPC response.
+ void moveControls(expanded, finalPoint ?? start.point);
+ if (event.currentTarget.hasPointerCapture(event.pointerId)) event.currentTarget.releasePointerCapture(event.pointerId);
+ }
+
+ return <div className="pointer-events-none fixed inset-0 select-none text-12 text-[var(--text-primary)]">
+ <div className="absolute border-2 border-[var(--focus-ring)]" style={{ left: begin.selection.x - 2, top: begin.selection.y - 2, width: begin.selection.width + 4, height: begin.selection.height + 4 }} />
+ {phase === 'countdown' && <div className="absolute flex items-center justify-center" style={{ left: begin.selection.x, top: begin.selection.y, width: begin.selection.width, height: begin.selection.height }}>
+ <span role="status" aria-label={t('regionScreenshot.live.countdown', { count: countdown })} className="flex h-40 w-40 items-center justify-center rounded-full border border-[var(--border-default)] bg-[var(--surface-elevated)] font-semibold leading-none tabular-nums shadow-lg" style={{ fontSize: 64 }}>{countdown}</span>
+ </div>}
+ <section aria-label={t('regionScreenshot.live.video')} className="pointer-events-auto absolute flex flex-col gap-1 overflow-hidden rounded-xl border border-[var(--border-default)] bg-[var(--surface-elevated)] p-2" style={{ left: controls.x, top: controls.y, width: controls.width, height: controls.height }}>
+ <div className="flex shrink-0 items-center gap-1">
+ <button type="button" aria-label={t('regionScreenshot.moveToolbar')} className="flex h-7 min-w-0 flex-1 touch-none cursor-grab items-center gap-1 rounded-full text-left hover:bg-[var(--surface-hover)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--focus-ring)] active:cursor-grabbing"
+ onPointerDown={(event) => {
+ if (event.button !== 0 || !event.isPrimary) return;
+ event.preventDefault();
+ drag.current = { pointerId: event.pointerId, x: event.clientX, y: event.clientY, left: controls.x, top: controls.y, point: controls };
+ event.currentTarget.setPointerCapture(event.pointerId);
+ void moveControls(expanded, controls, true);
+ }}
+ onPointerMove={(event) => { const point = dragPoint(event); if (point && drag.current) { drag.current.point = point; void moveControls(expanded, point, true); } }}
+ onPointerUp={(event) => endDrag(event, dragPoint(event))}
+ onPointerCancel={(event) => endDrag(event)}
+ onLostPointerCapture={(event) => endDrag(event)}
+ onKeyDown={(event) => { const delta = { ArrowLeft: [-10, 0], ArrowRight: [10, 0], ArrowUp: [0, -10], ArrowDown: [0, 10] }[event.key]; if (delta) { event.preventDefault(); void moveControls(expanded, { x: controls.x + delta[0], y: controls.y + delta[1] }); } }}>
+ <span className="flex w-7 shrink-0 justify-center"><GripVertical size={14} /></span>
+ <span className="text-[var(--text-secondary)]">{begin.mode === 'gif' ? 'GIF' : 'WebM'}</span>
+ <span className="whitespace-nowrap font-medium tabular-nums">{`${Math.floor(elapsed / 60_000)}:${String(Math.floor(elapsed / 1000) % 60).padStart(2, '0')}`} / 5:00</span>
+ </button>
+ {(phase === 'capturing' || phase === 'paused') && <>
+ <Button size="xs" variant="secondary" tone={expanded ? 'default' : 'quiet'} className="w-7 px-0" aria-label={t('regionScreenshot.live.annotate')} aria-pressed={expanded} onClick={() => void moveControls(!expanded)}><Pencil size={14} /></Button>
+ <Button size="xs" variant="secondary" tone="quiet" className="w-7 px-0" aria-label={t(`regionScreenshot.live.${phase === 'capturing' ? 'pause' : 'resume'}`)} onClick={pause}>{phase === 'capturing' ? <Pause size={14} /> : <Play size={14} />}</Button>
+ </>}
+ {phase !== 'countdown' && phase !== 'done' && <Button size="xs" variant="cta" disabled={phase === 'finishing'} onClick={() => void finish()}><Square size={12} />{t(`regionScreenshot.live.${phase === 'finishing' ? 'finishing' : 'finish'}`)}</Button>}
+ {phase === 'done' && result && <>
+ <Button size="xs" variant="secondary" onClick={() => void previewRecording(result)}>{t('regionScreenshot.live.preview')}</Button>
+ <Button size="xs" variant="cta" disabled={saving} onClick={() => void saveRecording()}>{t('regionScreenshot.save')}</Button>
+ </>}
+ <Button size="xs" variant="secondary" tone="quiet" className="w-7 px-0" disabled={saving || phase === 'finishing'} aria-label={t('regionScreenshot.cancel')} onClick={() => bridge.cancel(token)}><X size={14} /></Button>
+ </div>
+ <p role={error ? 'alert' : 'status'} className={`truncate ${error ? 'text-[var(--text-danger)]' : 'text-[var(--text-secondary)]'}`} title={error ? t(`regionScreenshot.live.${error}`) : undefined}>{t(`regionScreenshot.live.${error || (phase === 'countdown' ? 'countdownHint' : phase === 'finishing' ? 'finishing' : status || (phase === 'paused' ? 'paused' : phase === 'done' ? 'done' : 'recording'))}`)}</p>
+ {expanded && <><div className="flex min-h-12 flex-1 items-center justify-center overflow-hidden">
+ <canvas ref={preview} aria-label={t('regionScreenshot.live.preview')} className="block max-h-full max-w-full" style={{ objectFit: 'contain', cursor: tool ? 'crosshair' : 'default' }}
+ onPointerDown={(event) => {
+ if (!tool || phase === 'done' || phase === 'finishing') return;
+ event.currentTarget.setPointerCapture(event.pointerId);
+ runtime.current.draft = { kind: tool, points: [point(event)] };
+ }}
+ onPointerMove={(event) => {
+ const draft = runtime.current.draft;
+ if (!draft) return;
+ if (draft.points.length < 4000) draft.points.push(point(event));
+ paint(runtime.current.bitmap);
+ }}
+ onPointerUp={() => {
+ const state = runtime.current;
+ if (state.draft && state.marks.length < 100) state.marks.push(state.draft);
+ state.draft = null; paint(state.bitmap);
+ }} onPointerCancel={() => { runtime.current.draft = null; paint(runtime.current.bitmap); }} />
+ </div>
+ <div className="flex flex-wrap gap-1">
+ {(['pen', 'arrow', 'rect'] as const).map((kind) => <Button key={kind} size="xs" variant="secondary" tone={tool === kind ? 'default' : 'quiet'} aria-pressed={tool === kind} onClick={() => setTool(tool === kind ? null : kind)}>{t(`regionScreenshot.tools.${kind}`)}</Button>)}
+ <Button size="xs" variant="secondary" tone="quiet" onClick={() => { runtime.current.marks.pop(); paint(runtime.current.bitmap); }}>{t('regionScreenshot.undo')}</Button>
+ </div>
+ </>}
+ </section>
+ </div>;
+}
diff --git a/apps/desktop/src/renderer/features/region-screenshot/Magnifier.tsx b/apps/desktop/src/renderer/features/region-screenshot/Magnifier.tsx
new file mode 100644
index 0000000000..b382c25e60
--- /dev/null
+++ b/apps/desktop/src/renderer/features/region-screenshot/Magnifier.tsx
@@ -0,0 +1,106 @@
+import { useEffect, useRef } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { clampIntoArea, type RegionPoint, type RegionRect, type RegionSize } from '../../../shared/regionScreenshot';
+import { SCREENSHOT_OVERLAY } from './screenshotColors';
+
+/** 放大镜取样边长 (原图像素, 奇数让指针落在正中一格) 与放大倍数。 */
+const SAMPLE = 15;
+const ZOOM = 8;
+const VIEW = SAMPLE * ZOOM;
+const OFFSET = 20;
+
+export interface PixelColor {
+ r: number;
+ g: number;
+ b: number;
+}
+
+export function colorHex({ r, g, b }: PixelColor): string {
+ return `#${[r, g, b].map((v) => v.toString(16).padStart(2, '0')).join('').toUpperCase()}`;
+}
+
+export function colorRgb({ r, g, b }: PixelColor): string {
+ return `${r}, ${g}, ${b}`;
+}
+
+/**
+ * 跟随指针的放大镜: 放大原图像素、十字线标出当前像素, 下方是物理像素坐标与颜色。
+ * 放大区与色块显示的是用户截图内容本身; 外框与文字走主题 token。
+ */
+export function Magnifier({
+ frame,
+ frameSize,
+ point,
+ viewport,
+ bounds,
+ color,
+ scaleFactor,
+}: {
+ frame: HTMLCanvasElement | null;
+ frameSize: RegionSize;
+ point: RegionPoint;
+ viewport: RegionSize;
+ /** 放大镜可放置的区域 (避开刘海与 Dock); 缺省为整个视口。 */
+ bounds?: RegionRect;
+ color: PixelColor | null;
+ scaleFactor: number;
+}) {
+ const { t } = useTranslation();
+ const canvasRef = useRef<HTMLCanvasElement>(null);
+ const fx = Math.floor((point.x * frameSize.width) / viewport.width);
+ const fy = Math.floor((point.y * frameSize.height) / viewport.height);
+
+ useEffect(() => {
+ const canvas = canvasRef.current;
+ if (!canvas || !frame) return;
+ const dpr = window.devicePixelRatio || 1;
+ canvas.width = Math.round(VIEW * dpr);
+ canvas.height = Math.round(VIEW * dpr);
+ const ctx = canvas.getContext('2d');
+ if (!ctx) return;
+ ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+ ctx.imageSmoothingEnabled = false;
+ ctx.fillStyle = SCREENSHOT_OVERLAY.backdrop;
+ ctx.fillRect(0, 0, VIEW, VIEW);
+ const half = Math.floor(SAMPLE / 2);
+ ctx.drawImage(frame, fx - half, fy - half, SAMPLE, SAMPLE, 0, 0, VIEW, VIEW);
+ // 十字线与中心格: 覆盖在任意截图内容上的功能像素, 暗色带 + 白框保证都看得见。
+ const center = half * ZOOM;
+ ctx.fillStyle = SCREENSHOT_OVERLAY.crosshair;
+ ctx.fillRect(0, center, VIEW, ZOOM);
+ ctx.fillRect(center, 0, ZOOM, VIEW);
+ ctx.strokeStyle = SCREENSHOT_OVERLAY.edge;
+ ctx.lineWidth = 1;
+ ctx.strokeRect(center + 0.5, center + 0.5, ZOOM - 1, ZOOM - 1);
+ }, [frame, fx, fy]);
+
+ const width = VIEW + 2;
+ const height = VIEW + 58;
+ const area = bounds ?? { x: 0, y: 0, width: viewport.width, height: viewport.height };
+ const left = point.x + OFFSET + width > area.x + area.width ? point.x - OFFSET - width : point.x + OFFSET;
+ const top = point.y + OFFSET + height > area.y + area.height ? point.y - OFFSET - height : point.y + OFFSET;
+ const position = clampIntoArea({ x: left, y: top }, { width, height }, area);
+
+ return (
+ <div
+ className="pointer-events-none fixed overflow-hidden rounded-xl border border-[var(--border-default)] bg-[var(--surface-elevated)]"
+ style={{ left: position.x, top: position.y, width }}
+ >
+ <canvas ref={canvasRef} style={{ width: VIEW, height: VIEW, display: 'block' }} />
+ <div className="flex flex-col gap-0.5 border-t border-[var(--border-default)] px-2 py-1.5 text-12 leading-[1.35] tabular-nums">
+ <div className="text-[var(--text-secondary)]">
+ {Math.floor(point.x * scaleFactor)}, {Math.floor(point.y * scaleFactor)}
+ </div>
+ <div className="flex items-center gap-1.5 text-[var(--text-primary)]">
+ <span
+ className="inline-block h-3 w-3 shrink-0 rounded-sm border border-[var(--border-default)]"
+ style={{ background: color ? colorHex(color) : 'transparent' }}
+ />
+ <span>{color ? colorHex(color) : '—'}</span>
+ </div>
+ <div className="text-[var(--text-tertiary)]">{t('regionScreenshot.magnifier.copyHint')}</div>
+ </div>
+ </div>
+ );
+}
diff --git a/apps/desktop/src/renderer/features/region-screenshot/PinView.tsx b/apps/desktop/src/renderer/features/region-screenshot/PinView.tsx
new file mode 100644
index 0000000000..f1bfeeb30e
--- /dev/null
+++ b/apps/desktop/src/renderer/features/region-screenshot/PinView.tsx
@@ -0,0 +1,162 @@
+import { useEffect, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { MousePointer2 } from 'lucide-react';
+
+import i18n from '@/i18n';
+import type { RegionScreenshotPinState } from '../../../shared/regionScreenshot';
+import { bitmapToImageData, type RegionScreenshotPinBridge } from './bridge';
+import { SCREENSHOT_OVERLAY } from './screenshotColors';
+import { isPreciseWheel, pinchZoomFactor } from './trackpad';
+
+/** 触控板一次滑动会产生很多滚轮事件, 累计到这个量才缩放一级。 */
+const WHEEL_STEP = 40;
+/** 与 main 的单级缩放倍率一致: 捏合按连续倍率换算成 (小数) 级数。 */
+const ZOOM_STEP_LOG = Math.log(1.1);
+const ZOOM_BADGE_MS = 900;
+
+/**
+ * 贴图窗口内容: 整窗显示截图。拖动移动、滚轮缩放 (macOS 触控板用双指捏合连续缩放,
+ * 双指滑动不缩放)、Ctrl / ⌘ + 滚轮调不透明度、
+ * 双击或 Esc 关闭、右键菜单; 鼠标穿透时只在右上角留一个「恢复」按钮接收点击。
+ * 截图本身是用户内容; 描边、按钮与缩放提示走主题 token。
+ */
+export function PinView({ bridge }: { bridge: RegionScreenshotPinBridge }) {
+ const { t } = useTranslation();
+ const isMac = window.electronAPI?.platform === 'darwin';
+ const canvasRef = useRef<HTMLCanvasElement>(null);
+ const [state, setState] = useState<RegionScreenshotPinState>({ opacity: 1, passThrough: false, zoom: 1 });
+ const [zoomBadge, setZoomBadge] = useState(false);
+ const dragging = useRef(false);
+ const frame = useRef<number | null>(null);
+ const wheel = useRef(0);
+ const pinch = useRef<{ steps: number; x: number; y: number; frame: number | null }>({ steps: 0, x: 0, y: 0, frame: null });
+ const lastZoom = useRef(1);
+
+ useEffect(() => {
+ const offInit = bridge.onInit((payload) => {
+ if (payload.locale && i18n.language !== payload.locale) void i18n.changeLanguage(payload.locale);
+ const canvas = canvasRef.current;
+ if (!canvas) return;
+ canvas.width = payload.image.width;
+ canvas.height = payload.image.height;
+ canvas.getContext('2d')?.putImageData(bitmapToImageData(payload.image), 0, 0);
+ requestAnimationFrame(() => bridge.painted());
+ });
+ const offState = bridge.onState((next) => {
+ setState(next);
+ if (next.zoom !== lastZoom.current) {
+ lastZoom.current = next.zoom;
+ setZoomBadge(true);
+ }
+ });
+ bridge.shellReady();
+ return () => {
+ offInit();
+ offState();
+ };
+ }, [bridge]);
+
+ useEffect(() => {
+ if (!zoomBadge) return;
+ const timer = setTimeout(() => setZoomBadge(false), ZOOM_BADGE_MS);
+ return () => clearTimeout(timer);
+ }, [zoomBadge, state.zoom]);
+
+ useEffect(() => {
+ const onKeyDown = (event: KeyboardEvent) => {
+ const mod = isMac ? event.metaKey : event.ctrlKey;
+ const key = event.key.toLowerCase();
+ if (event.key === 'Escape') bridge.command('close');
+ else if (mod && key === 'c') bridge.command('copy');
+ else if (mod && key === 's') {
+ event.preventDefault();
+ bridge.command('save');
+ } else if (!mod && key === '0') bridge.command('zoom-reset');
+ };
+ window.addEventListener('keydown', onKeyDown);
+ return () => window.removeEventListener('keydown', onKeyDown);
+ }, [bridge, isMac]);
+
+ return (
+ <div
+ className="fixed inset-0 select-none overflow-hidden"
+ style={{ cursor: 'move', background: SCREENSHOT_OVERLAY.backdrop }}
+ onPointerDown={(event) => {
+ if (event.button !== 0 || state.passThrough) return;
+ event.currentTarget.setPointerCapture(event.pointerId);
+ dragging.current = true;
+ bridge.dragStart();
+ }}
+ onPointerMove={() => {
+ if (!dragging.current || frame.current !== null) return;
+ frame.current = requestAnimationFrame(() => {
+ frame.current = null;
+ if (dragging.current) bridge.dragMove();
+ });
+ }}
+ onPointerUp={(event) => {
+ dragging.current = false;
+ if (event.currentTarget.hasPointerCapture(event.pointerId)) {
+ event.currentTarget.releasePointerCapture(event.pointerId);
+ }
+ }}
+ onDoubleClick={() => {
+ if (!state.passThrough) bridge.command('close');
+ }}
+ onContextMenu={(event) => {
+ event.preventDefault();
+ if (!state.passThrough) bridge.menu();
+ }}
+ onWheel={(event) => {
+ if (state.passThrough) return;
+ if (isMac && event.ctrlKey) {
+ // 双指捏合: 每帧合并一次, 按捏合倍率连续缩放, 以指针为锚点。
+ const gesture = pinch.current;
+ gesture.steps += Math.log(pinchZoomFactor(event.deltaY)) / ZOOM_STEP_LOG;
+ gesture.x = event.clientX;
+ gesture.y = event.clientY;
+ gesture.frame ??= requestAnimationFrame(() => {
+ gesture.frame = null;
+ const steps = gesture.steps;
+ gesture.steps = 0;
+ if (steps) bridge.zoom(steps, gesture.x, gesture.y);
+ });
+ return;
+ }
+ // macOS 触控板双指滑动是最常用的手势, 不拿来缩放; 鼠标滚轮与 ⌘ + 滑动照旧。
+ if (isMac && !event.metaKey && isPreciseWheel(event.nativeEvent)) return;
+ wheel.current += event.deltaY;
+ if (Math.abs(wheel.current) < WHEEL_STEP) return;
+ const steps = wheel.current < 0 ? 1 : -1;
+ wheel.current = 0;
+ if (isMac ? event.metaKey : event.ctrlKey) bridge.opacity(steps);
+ else bridge.zoom(steps, event.clientX, event.clientY);
+ }}
+ >
+ <canvas ref={canvasRef} className="absolute inset-0 block h-full w-full" />
+ <div
+ className="pointer-events-none absolute inset-0"
+ style={{ boxShadow: 'inset 0 0 0 1px var(--border-default)' }}
+ />
+ {zoomBadge && (
+ <div className="pointer-events-none absolute left-2 top-2 rounded-full border border-[var(--border-default)] bg-[var(--surface-elevated)] px-2 py-0.5 text-12 tabular-nums text-[var(--text-primary)]">
+ {Math.round(state.zoom * 100)}%
+ </div>
+ )}
+ {state.passThrough && (
+ <button
+ type="button"
+ aria-label={t('regionScreenshot.pin.unlock')}
+ title={t('regionScreenshot.pin.unlock')}
+ className="absolute right-1.5 top-1.5 inline-flex h-7 w-7 items-center justify-center rounded-full border border-[var(--border-default)] bg-[var(--surface-elevated)] text-[var(--text-secondary)] hover:text-[var(--text-primary)]"
+ onPointerEnter={() => bridge.unlockHover(true)}
+ onPointerLeave={() => bridge.unlockHover(false)}
+ onPointerDown={(event) => event.stopPropagation()}
+ onClick={() => bridge.command('unlock')}
+ >
+ <MousePointer2 size={14} />
+ </button>
+ )}
+ </div>
+ );
+}
diff --git a/apps/desktop/src/renderer/features/region-screenshot/RecordingPreview.tsx b/apps/desktop/src/renderer/features/region-screenshot/RecordingPreview.tsx
new file mode 100644
index 0000000000..32e76421af
--- /dev/null
+++ b/apps/desktop/src/renderer/features/region-screenshot/RecordingPreview.tsx
@@ -0,0 +1,95 @@
+import { useEffect, useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { Minus, RotateCcw, X } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import type { RecordingPreviewDocument } from '../../../shared/regionCapture';
+
+export interface RecordingPreviewBridge {
+ ready(): void; failed(): void;
+ onBegin(callback: (document: RecordingPreviewDocument) => void): () => void;
+ onEnd(callback: () => void): () => void;
+ painted(token: string): void; close(token: string): void; minimize(token: string): void;
+ save(token: string): Promise<boolean>;
+ copy(token: string): Promise<boolean>;
+}
+declare global { interface Window { recordingPreview?: RecordingPreviewBridge } }
+
+export function RecordingPreview({ document: clip, bridge }: { document: RecordingPreviewDocument; bridge: RecordingPreviewBridge }) {
+ const { t } = useTranslation();
+ const [url, setUrl] = useState('');
+ const [action, setAction] = useState<'save' | 'copy' | null>(null);
+ const saving = action !== null;
+ const [status, setStatus] = useState('');
+ const [error, setError] = useState('');
+ const [replay, setReplay] = useState(0);
+ const [ready, setReady] = useState(false);
+ const video = useRef<HTMLVideoElement>(null);
+ useEffect(() => {
+ const next = URL.createObjectURL(new Blob([clip.bytes], { type: clip.format === 'gif' ? 'image/gif' : 'video/webm' }));
+ setUrl(next);
+ return () => URL.revokeObjectURL(next);
+ }, [clip]);
+ useEffect(() => {
+ if (!ready && !error) return;
+ const frame = requestAnimationFrame(() => bridge.painted(clip.token));
+ return () => cancelAnimationFrame(frame);
+ }, [ready, error, clip.token, bridge]);
+ useEffect(() => {
+ let fullscreen = !!document.fullscreenElement;
+ let exitedFullscreenAt = -Infinity;
+ const fullscreenChanged = () => {
+ const next = !!document.fullscreenElement;
+ if (fullscreen && !next) exitedFullscreenAt = performance.now();
+ fullscreen = next;
+ };
+ const visibility = () => { if (document.hidden) video.current?.pause(); };
+ const escape = (event: KeyboardEvent) => {
+ if (event.key !== 'Escape' || saving) return;
+ if (fullscreen || document.fullscreenElement) {
+ void document.exitFullscreen().catch(() => {});
+ return;
+ }
+ // Chromium may exit fullscreen before delivering this same Esc to the page.
+ if (performance.now() - exitedFullscreenAt < 250) return;
+ bridge.close(clip.token);
+ };
+ document.addEventListener('fullscreenchange', fullscreenChanged);
+ document.addEventListener('visibilitychange', visibility);
+ window.addEventListener('keydown', escape);
+ return () => { document.removeEventListener('fullscreenchange', fullscreenChanged); document.removeEventListener('visibilitychange', visibility); window.removeEventListener('keydown', escape); };
+ }, [bridge, clip.token, saving]);
+ async function save() {
+ setAction('save'); setStatus(''); setError('');
+ try { if (await bridge.save(clip.token)) setStatus('saved'); }
+ catch { setError('exportFailed'); }
+ finally { setAction(null); }
+ }
+ async function copy() {
+ setAction('copy'); setStatus(''); setError('');
+ try {
+ if (await bridge.copy(clip.token)) setStatus('copied');
+ else setError('copyFailed');
+ } catch { setError('copyFailed'); }
+ finally { setAction(null); }
+ }
+ return <div className="flex h-screen flex-col bg-[var(--surface)] text-[var(--text-primary)]">
+ <div className="flex h-11 shrink-0 items-center gap-2 border-b border-[var(--border-default)] px-3 [-webkit-app-region:drag] [&_button]:[-webkit-app-region:no-drag]">
+ <span className="text-12">{t('regionScreenshot.live.preview')} · {clip.format === 'gif' ? 'GIF' : 'WebM'}</span>
+ <span className="flex-1" />
+ <Button size="xs" variant="secondary" tone="quiet" className="w-7 px-0" aria-label={t('titleBar.minimize')} onClick={() => bridge.minimize(clip.token)}><Minus size={14} /></Button>
+ <Button size="xs" variant="secondary" tone="quiet" className="w-7 px-0" disabled={saving} aria-label={t('titleBar.close')} onClick={() => bridge.close(clip.token)}><X size={14} /></Button>
+ </div>
+ <div className="relative flex min-h-0 flex-1 items-center justify-center overflow-hidden p-4">
+ {!ready && !error && <span role="status" className="absolute text-13 text-[var(--text-secondary)]">{t('regionScreenshot.editor.loading')}</span>}
+ {url && (clip.format === 'gif'
+ ? <img key={replay} src={url} alt={t('regionScreenshot.live.preview')} className="max-h-full max-w-full object-contain" onLoad={() => setReady(true)} onError={() => setError('playbackFailed')} />
+ : <video ref={video} src={url} controls playsInline className="h-full w-full object-contain" aria-label={t('regionScreenshot.live.preview')} onLoadedData={() => setReady(true)} onError={() => setError('playbackFailed')} />)}
+ </div>
+ <div className="flex shrink-0 flex-wrap items-center gap-2 border-t border-[var(--border-default)] p-3">
+ {clip.format === 'gif' && <Button size="sm" variant="secondary" onClick={() => setReplay((value) => value + 1)}><RotateCcw size={14} />{t('regionScreenshot.live.replay')}</Button>}
+ <span role={error ? 'alert' : 'status'} className={`min-w-0 flex-1 text-12 ${error ? 'text-[var(--text-danger)]' : 'text-[var(--text-secondary)]'}`}>{(error || status) && t(`regionScreenshot.live.${error || status}`)}</span>
+ <Button size="sm" variant="secondary" loading={action === 'copy'} disabled={saving} onClick={() => void copy()}>{t('regionScreenshot.copy')}</Button>
+ <Button size="sm" variant="cta" loading={action === 'save'} disabled={saving} onClick={() => void save()}>{t('regionScreenshot.save')}</Button>
+ </div>
+ </div>;
+}
diff --git a/apps/desktop/src/renderer/features/region-screenshot/RegionScreenshotOverlay.tsx b/apps/desktop/src/renderer/features/region-screenshot/RegionScreenshotOverlay.tsx
new file mode 100644
index 0000000000..1ce07a4208
--- /dev/null
+++ b/apps/desktop/src/renderer/features/region-screenshot/RegionScreenshotOverlay.tsx
@@ -0,0 +1,1278 @@
+import {
+ useCallback,
+ useEffect,
+ useLayoutEffect,
+ useRef,
+ useState,
+ type CSSProperties,
+ type MouseEvent as ReactMouseEvent,
+ type PointerEvent as ReactPointerEvent,
+ type WheelEvent as ReactWheelEvent,
+} from 'react';
+import { Button } from '@/components/ui/button';
+import { useTranslation } from 'react-i18next';
+
+import i18n from '@/i18n';
+import { getInitialThemeVariant } from '@/hooks/useTheme';
+import { themeService } from '@/themes/theme-service';
+import {
+ clampIntoArea,
+ isRegionArrowKey,
+ moveRegion,
+ normalizeRegionSelection,
+ nudgeRegion,
+ rectContains,
+ rectFromDrag,
+ regionHandleAt,
+ regionSelectionToImageCrop,
+ resizeRegion,
+ sameRegion,
+ snapCandidates,
+ topWindowAt,
+ type RegionHandle,
+ type RegionPoint,
+ type RegionRect,
+ type RegionScreenshotAction,
+ type RegionScreenshotBegin,
+ type RegionScreenshotBitmap,
+ type RegionScreenshotWindow,
+ type RegionSize,
+} from '../../../shared/regionScreenshot';
+import {
+ annotationAt,
+ annotationBounds,
+ constrainShape,
+ DEFAULT_ANNOTATION_COLOR,
+ DEFAULT_MARKER_COLOR,
+ drawAnnotations,
+ isMeaningfulAnnotation,
+ moveAnnotation,
+ nextStepNumber,
+ TEXT_LINE_HEIGHT,
+ TEXT_SIZE,
+ textBounds,
+ textFont,
+ type Annotation,
+ type AnnotationSize,
+ type AnnotationSource,
+ type AnnotationTool,
+ type ShapeAnnotation,
+ type TextAnnotation,
+} from './annotations';
+import { bitmapToImageData, imageDataToBitmap, type RegionScreenshotOverlayBridge } from './bridge';
+import { colorHex, colorRgb, Magnifier, type PixelColor } from './Magnifier';
+import { ScreenshotModeBar, ScreenshotStyleBar, ScreenshotToolbar, TOOL_SHORTCUTS, type ScreenshotMode } from './ScreenshotToolbar';
+import { SCREENSHOT_INK, SCREENSHOT_OVERLAY, type ScreenshotInk } from './screenshotColors';
+import { LiveCapturePanel } from './LiveCapturePanel';
+import { ScrollCaptureOverlay } from './ScrollCaptureOverlay';
+import { ScreenshotEditorViewport } from './ScreenshotEditorViewport';
+import { isPreciseWheel, WHEEL_GESTURE_GAP_MS } from './trackpad';
+import type { RegionCaptureBegin, RegionCaptureMode } from '../../../shared/regionCapture';
+
+/** 小于这个尺寸的拖动视为误点, 不形成选区。 */
+const MIN_SELECTION = 4;
+/** 按下后移动超过这个距离才算拖动 (否则是单击选中吸附区域)。 */
+const DRAG_THRESHOLD = 3;
+const HANDLE_TOLERANCE = 6;
+const GAP = 8;
+/** 触控板一次滑动会产生很多滚轮事件, 累计到这个量才切换一级。 */
+const WHEEL_STEP = 60;
+
+interface ActiveSession {
+ token: string;
+ scaleFactor: number;
+ viewport: RegionSize;
+ windows: RegionScreenshotWindow[];
+ lastRegion: RegionRect | null;
+ frameSize: RegionSize;
+ frameData: ImageData;
+ /** 界面元素可用区域: 避开菜单栏、刘海与 Dock / 任务栏。 */
+ safeArea: RegionRect;
+}
+
+type Drag =
+ | { kind: 'select'; anchor: RegionPoint; moved: boolean }
+ | { kind: 'move'; start: RegionRect; origin: RegionPoint }
+ | { kind: 'resize'; start: RegionRect; handle: RegionHandle }
+ | { kind: 'draw'; origin: RegionPoint }
+ | { kind: 'move-annotation'; original: Annotation; origin: RegionPoint; moved: boolean };
+
+interface ToolStyle {
+ color: ScreenshotInk;
+ size: AnnotationSize;
+}
+
+interface Editing {
+ /** 正在改的已有文字标注; 新建时为 null。 */
+ id: string | null;
+ at: RegionPoint;
+ color: ScreenshotInk;
+ size: AnnotationSize;
+ text: string;
+}
+
+const defaultStyles = (): Record<AnnotationTool, ToolStyle> => ({
+ rect: { color: DEFAULT_ANNOTATION_COLOR, size: 1 },
+ ellipse: { color: DEFAULT_ANNOTATION_COLOR, size: 1 },
+ line: { color: DEFAULT_ANNOTATION_COLOR, size: 1 },
+ arrow: { color: DEFAULT_ANNOTATION_COLOR, size: 1 },
+ pen: { color: DEFAULT_ANNOTATION_COLOR, size: 1 },
+ marker: { color: DEFAULT_MARKER_COLOR, size: 1 },
+ text: { color: DEFAULT_ANNOTATION_COLOR, size: 1 },
+ mosaic: { color: DEFAULT_ANNOTATION_COLOR, size: 1 },
+ blur: { color: DEFAULT_ANNOTATION_COLOR, size: 1 },
+ step: { color: DEFAULT_ANNOTATION_COLOR, size: 1 },
+});
+
+const HANDLE_CURSORS: Record<RegionHandle, string> = {
+ n: 'ns-resize',
+ s: 'ns-resize',
+ e: 'ew-resize',
+ w: 'ew-resize',
+ ne: 'nesw-resize',
+ sw: 'nesw-resize',
+ nw: 'nwse-resize',
+ se: 'nwse-resize',
+};
+
+const HANDLES: RegionHandle[] = ['nw', 'n', 'ne', 'e', 'se', 's', 'sw', 'w'];
+
+const TOOL_BY_KEY = Object.fromEntries(
+ Object.entries(TOOL_SHORTCUTS).map(([tool, key]) => [key.toLowerCase(), tool as AnnotationTool]),
+);
+
+let idSeed = 0;
+const nextId = () => `a${++idSeed}`;
+
+function handlePosition(rect: RegionRect, handle: RegionHandle): RegionPoint {
+ const x = handle.includes('w') ? rect.x : handle.includes('e') ? rect.x + rect.width : rect.x + rect.width / 2;
+ const y = handle.includes('n') ? rect.y : handle.includes('s') ? rect.y + rect.height : rect.y + rect.height / 2;
+ return { x, y };
+}
+
+/**
+ * 框选浮层。每块显示器一个, 预热后隐藏复用: BEGIN 时绘制定格画面并清空交互态,
+ * END 时清空画面与全部状态。
+ *
+ * 选区描边、暗化遮罩、手柄与选中标注的虚线框是覆盖在任意屏幕内容上的功能像素,
+ * 两种模式取同一值 (白描边 + 暗色外圈); 工具条、放大镜、尺寸标签等界面 chrome
+ * 一律走主题 token, 跟随 Cindy 的浅色 / 深色模式。
+ */
+export function RegionScreenshotOverlay({ bridge, imageEditor = false }: { bridge: RegionScreenshotOverlayBridge; imageEditor?: boolean }) {
+ const { t } = useTranslation();
+ const isMac = window.electronAPI?.platform === 'darwin';
+ const modLabel = isMac ? '⌘' : 'Ctrl+';
+ const rootRef = useRef<HTMLDivElement>(null);
+ const frameRef = useRef<HTMLCanvasElement>(null);
+ const annotationCanvasRef = useRef<HTMLCanvasElement>(null);
+ const toolbarRef = useRef<HTMLDivElement>(null);
+ const textAreaRef = useRef<HTMLTextAreaElement>(null);
+
+ const [session, setSession] = useState<ActiveSession | null>(null);
+ const [activeDisplay, setActiveDisplay] = useState(false);
+ const [modeBarCenter, setModeBarCenter] = useState<number | null>(null);
+ const [live, setLive] = useState<RegionCaptureBegin | null>(null);
+ const [liveError, setLiveError] = useState(false);
+ const [captureMode, setCaptureMode] = useState<ScreenshotMode>('image');
+ const [recordingFormat, setRecordingFormat] = useState<'video' | 'gif'>('video');
+ const liveRef = useRef(false);
+ const [longResult, setLongResult] = useState<{ image: RegionScreenshotBitmap; selection: RegionRect } | null>(null);
+ const longResultRef = useRef(longResult);
+ longResultRef.current = longResult;
+ const [selection, setSelection] = useState<RegionRect | null>(null);
+ const [hover, setHover] = useState<{ candidates: RegionRect[]; level: number } | null>(null);
+ const [pointer, setPointer] = useState<RegionPoint | null>(null);
+ const [drag, setDrag] = useState<Drag | null>(null);
+ const [tool, setTool] = useState<AnnotationTool | null>(null);
+ const [styles, setStyles] = useState(defaultStyles);
+ const [annotations, setAnnotations] = useState<Annotation[]>([]);
+ const [undoStack, setUndoStack] = useState<Annotation[][]>([]);
+ const [redoStack, setRedoStack] = useState<Annotation[][]>([]);
+ const [draft, setDraft] = useState<Annotation | null>(null);
+ const [selectedId, setSelectedId] = useState<string | null>(null);
+ const [editing, setEditing] = useState<Editing | null>(null);
+ const [aiMenuOpen, setAiMenuOpen] = useState(false);
+ const [toolbarSize, setToolbarSize] = useState<RegionSize>({ width: 640, height: 38 });
+ const [overToolbar, setOverToolbar] = useState(false);
+
+ // 事件处理里读最新值, 避免每次渲染重新绑定全局监听。
+ const state = useRef({
+ session,
+ selection,
+ hover,
+ pointer,
+ drag,
+ tool,
+ styles,
+ annotations,
+ undoStack,
+ redoStack,
+ draft,
+ selectedId,
+ editing,
+ aiMenuOpen,
+ captureMode,
+ });
+ state.current = {
+ session,
+ selection,
+ hover,
+ pointer,
+ drag,
+ tool,
+ styles,
+ annotations,
+ undoStack,
+ redoStack,
+ draft,
+ selectedId,
+ editing,
+ aiMenuOpen,
+ captureMode,
+ };
+ const busyRef = useRef(false);
+ /** BEGIN 带来的鼠标位置, 会话状态生效后立即据此吸附 (见下方 effect)。 */
+ const initialCursorRef = useRef<RegionPoint | null>(null);
+ const wheelRef = useRef(0);
+ /** 触控板一次滑动 (含惯性) 只切换一级吸附层级。 */
+ const wheelGestureRef = useRef({ last: 0, stepped: false });
+ const elementsRef = useRef<{
+ inFlight: boolean;
+ pending: RegionPoint | null;
+ cache: { windowId: number; rects: RegionRect[] } | null;
+ }>({ inFlight: false, pending: null, cache: null });
+
+ const viewport = session?.viewport ?? { width: window.innerWidth, height: window.innerHeight };
+ const safe = session?.safeArea ?? { x: 0, y: 0, width: viewport.width, height: viewport.height };
+ const isSelected = selection !== null && (drag === null || drag.kind !== 'select');
+
+ // ── 会话生命周期 ─────────────────────────────────────────────────────────
+
+ const resetInteraction = useCallback(() => {
+ setLive(null);
+ setCaptureMode('image');
+ setRecordingFormat('video');
+ setModeBarCenter(null);
+ setLongResult(null);
+ longResultRef.current = null;
+ liveRef.current = false;
+ setLiveError(false);
+ setSelection(null);
+ setHover(null);
+ setPointer(null);
+ setDrag(null);
+ setTool(null);
+ setAnnotations([]);
+ setUndoStack([]);
+ setRedoStack([]);
+ setDraft(null);
+ setSelectedId(null);
+ setEditing(null);
+ setAiMenuOpen(false);
+ setOverToolbar(false);
+ busyRef.current = false;
+ wheelRef.current = 0;
+ elementsRef.current = { inFlight: false, pending: null, cache: null };
+ }, []);
+
+ useEffect(() => {
+ const offBegin = bridge.onBegin((payload: RegionScreenshotBegin) => {
+ if (payload.locale && i18n.language !== payload.locale) void i18n.changeLanguage(payload.locale);
+ // 隐藏期间用户可能改了主题; 每次截图按当前设置重新套用。
+ themeService.applyTheme(getInitialThemeVariant().theme);
+ resetInteraction();
+ setActiveDisplay(imageEditor || payload.cursor !== null);
+ if (imageEditor) {
+ setLongResult({ image: payload.frame, selection: payload.lastRegion! });
+ setSelection({ x: 0, y: 0, width: payload.frame.width, height: payload.frame.height });
+ }
+ initialCursorRef.current = payload.cursor ?? null;
+ // 各工具上次用的颜色 / 粗细跨截图保留 (浮层复用, 本次运行内有效)。
+ const canvas = frameRef.current;
+ const frameData = bitmapToImageData(payload.frame);
+ if (canvas) {
+ canvas.width = payload.frame.width;
+ canvas.height = payload.frame.height;
+ canvas.getContext('2d')?.putImageData(frameData, 0, 0);
+ }
+ setSession({
+ token: payload.token,
+ scaleFactor: payload.scaleFactor,
+ viewport: payload.viewport,
+ windows: payload.windows,
+ lastRegion: payload.lastRegion,
+ frameSize: { width: payload.frame.width, height: payload.frame.height },
+ frameData,
+ safeArea: payload.safeArea ?? { x: 0, y: 0, width: payload.viewport.width, height: payload.viewport.height },
+ });
+ // 窗口显示后才会合成新帧: 等两帧再报告已绘制, main 随即淡入。
+ if (!imageEditor) requestAnimationFrame(() =>
+ requestAnimationFrame(() => {
+ bridge.painted(payload.token);
+ if (document.hasFocus()) bridge.focused(payload.token);
+ }),
+ );
+ });
+ const offEnd = bridge.onEnd(() => {
+ resetInteraction();
+ setActiveDisplay(false);
+ setSession(null);
+ const canvas = frameRef.current;
+ if (canvas) {
+ canvas.width = 0;
+ canvas.height = 0;
+ }
+ if (document.activeElement instanceof HTMLElement) document.activeElement.blur();
+ });
+ const offClear = bridge.onClear(() => {
+ setSelection(null);
+ setTool(null);
+ setAnnotations([]);
+ setUndoStack([]);
+ setRedoStack([]);
+ setDraft(null);
+ setSelectedId(null);
+ setEditing(null);
+ setAiMenuOpen(false);
+ });
+ const onFocus = () => {
+ const current = state.current.session;
+ if (current) bridge.focused(current.token);
+ };
+ const onBlur = () => setAiMenuOpen(false);
+ window.addEventListener('focus', onFocus);
+ window.addEventListener('blur', onBlur);
+ // 重新挂载 (热更新 / 错误边界重建) 时可能正处在一次截图中: 本页已没有会话状态,
+ // 请 main 结束它, 避免留下一块无法退出的黑屏。首次挂载时没有会话, main 忽略。
+ bridge.abandon();
+ bridge.shellReady();
+ return () => {
+ offBegin();
+ offEnd();
+ offClear();
+ window.removeEventListener('focus', onFocus);
+ window.removeEventListener('blur', onBlur);
+ };
+ }, [bridge, resetInteraction, imageEditor]);
+
+ useLayoutEffect(() => {
+ const canvas = frameRef.current;
+ if (!canvas || !session || live) return;
+ canvas.width = session.frameData.width;
+ canvas.height = session.frameData.height;
+ canvas.getContext('2d')?.putImageData(session.frameData, 0, 0);
+ if (imageEditor) bridge.painted(session.token);
+ }, [session, live, longResult, bridge, imageEditor]);
+
+ // ── 标注图层 ───────────────────────────────────────────────────────────
+
+ const annotationSource = useCallback((): AnnotationSource | null => {
+ const frame = frameRef.current;
+ const current = state.current.session;
+ if (!frame || !current) return null;
+ const rect = state.current.selection;
+ if (longResultRef.current && rect) return {
+ frame, ratioX: frame.width / rect.width, ratioY: frame.height / rect.height,
+ offsetX: rect.x, offsetY: rect.y,
+ };
+ return {
+ frame,
+ ratioX: current.frameSize.width / current.viewport.width,
+ ratioY: current.frameSize.height / current.viewport.height,
+ };
+ }, []);
+
+ useEffect(() => {
+ const canvas = annotationCanvasRef.current;
+ if (!canvas) return;
+ const dpr = imageEditor ? 1 : window.devicePixelRatio || 1;
+ const width = Math.round(viewport.width * dpr);
+ const height = Math.round(viewport.height * dpr);
+ if (canvas.width !== width || canvas.height !== height) {
+ canvas.width = width;
+ canvas.height = height;
+ }
+ const ctx = canvas.getContext('2d');
+ if (!ctx) return;
+ ctx.setTransform(1, 0, 0, 1, 0, 0);
+ ctx.clearRect(0, 0, width, height);
+ const source = annotationSource();
+ if (!source) return;
+ ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+ const visible = annotations.filter((a) => !(editing?.id && a.id === editing.id));
+ drawAnnotations(ctx, draft ? [...visible, draft] : visible, source);
+ }, [annotations, draft, editing?.id, viewport.width, viewport.height, annotationSource, session, imageEditor]);
+
+ // ── 撤销 / 重做 ────────────────────────────────────────────────────────
+
+ const commitAnnotations = useCallback((next: Annotation[]) => {
+ const { annotations: previous, undoStack: stack } = state.current;
+ const nextStack = [...stack, previous];
+ setUndoStack(nextStack);
+ setRedoStack([]);
+ setAnnotations(next);
+ state.current.annotations = next;
+ state.current.undoStack = nextStack;
+ state.current.redoStack = [];
+ }, []);
+
+ const undo = useCallback(() => {
+ const { undoStack: stack, redoStack: redoList, annotations: list } = state.current;
+ if (stack.length === 0) return;
+ setUndoStack(stack.slice(0, -1));
+ setRedoStack([...redoList, list]);
+ setAnnotations(stack[stack.length - 1]);
+ setSelectedId(null);
+ }, []);
+
+ const redo = useCallback(() => {
+ const { undoStack: stack, redoStack: redoList, annotations: list } = state.current;
+ if (redoList.length === 0) return;
+ setRedoStack(redoList.slice(0, -1));
+ setUndoStack([...stack, list]);
+ setAnnotations(redoList[redoList.length - 1]);
+ setSelectedId(null);
+ }, []);
+
+ /** 结束文字编辑, 返回提交后的标注列表 (导出时同步拿到最新结果)。 */
+ const commitEditing = useCallback((): Annotation[] => {
+ const current = state.current.editing;
+ const list = state.current.annotations;
+ if (!current) return list;
+ setEditing(null);
+ state.current.editing = null;
+ const text = current.text.replace(/\s+$/, '');
+ const existing = current.id ? list.find((a) => a.id === current.id) : undefined;
+ let next: Annotation[] | null = null;
+ if (existing && existing.kind === 'text') {
+ if (!text) next = list.filter((a) => a.id !== existing.id);
+ else if (text !== existing.text || current.color !== existing.color || current.size !== existing.size)
+ next = list.map((a) =>
+ a.id === existing.id ? { ...existing, text, color: current.color, size: current.size } : a,
+ );
+ } else if (text) {
+ const created: TextAnnotation = {
+ id: nextId(),
+ kind: 'text',
+ at: current.at,
+ text,
+ color: current.color,
+ size: current.size,
+ };
+ next = [...list, created];
+ }
+ if (next) commitAnnotations(next);
+ return next ?? list;
+ }, [commitAnnotations]);
+
+ // ── 吸附候选 ───────────────────────────────────────────────────────────
+
+ const refreshHover = useCallback((point: RegionPoint) => {
+ const current = state.current.session;
+ if (!current) return;
+ const window = topWindowAt(current.windows, point);
+ const cache = elementsRef.current.cache;
+ const elements = cache && window && cache.windowId === window.id ? cache.rects : [];
+ const candidates = snapCandidates(point, window, elements, current.viewport);
+ setHover((previous) => {
+ const keep = previous && previous.candidates[0] && sameRegion(previous.candidates[0], candidates[0]);
+ return { candidates, level: keep ? Math.min(previous.level, candidates.length - 1) : 0 };
+ });
+ }, []);
+
+ const requestElements = useCallback(
+ (point: RegionPoint) => {
+ const current = state.current.session;
+ if (!current) return;
+ const window = topWindowAt(current.windows, point);
+ if (!window) return;
+ const tracker = elementsRef.current;
+ if (tracker.inFlight) {
+ tracker.pending = point;
+ return;
+ }
+ tracker.inFlight = true;
+ void bridge
+ .elementsAt(current.token, window.id, point.x, point.y)
+ .then((rects) => {
+ if (state.current.session?.token !== current.token) return;
+ tracker.cache = { windowId: window.id, rects: Array.isArray(rects) ? rects : [] };
+ const latest = state.current.pointer;
+ if (latest && !state.current.selection && !state.current.drag) refreshHover(latest);
+ })
+ .catch(() => undefined)
+ .finally(() => {
+ tracker.inFlight = false;
+ const pending = tracker.pending;
+ tracker.pending = null;
+ if (pending && state.current.session?.token === current.token && !state.current.selection) {
+ requestElements(pending);
+ }
+ });
+ },
+ [bridge, refreshHover],
+ );
+
+ // 鼠标不动也要立刻高亮指针下的窗口 / 元素: 不等第一次 pointermove。
+ useEffect(() => {
+ const cursor = initialCursorRef.current;
+ if (!session || !cursor) return;
+ initialCursorRef.current = null;
+ setPointer(cursor);
+ state.current.pointer = cursor;
+ refreshHover(cursor);
+ requestElements(cursor);
+ }, [session, refreshHover, requestElements]);
+
+ // ── 导出 ───────────────────────────────────────────────────────────────
+
+ const runAction = useCallback(
+ async (action: RegionScreenshotAction) => {
+ const current = state.current.session;
+ const rect = state.current.selection;
+ const frame = frameRef.current;
+ if (!current || !rect || !frame || busyRef.current) return;
+ const list = commitEditing();
+ const long = longResultRef.current;
+ const selected = long?.selection ?? normalizeRegionSelection(rect, current.viewport, current.scaleFactor);
+ if (!selected) return;
+ const mapped = long ? { crop: { x: 0, y: 0, width: long.image.width, height: long.image.height }, output: { width: long.image.width, height: long.image.height } } : regionSelectionToImageCrop(
+ selected,
+ current.viewport,
+ current.frameSize,
+ current.scaleFactor,
+ );
+ const source = annotationSource();
+ if (!mapped || !source) return;
+ const { crop, output } = mapped;
+ const canvas = document.createElement('canvas');
+ canvas.width = output.width;
+ canvas.height = output.height;
+ const ctx = canvas.getContext('2d', { willReadFrequently: true });
+ if (!ctx) return;
+ ctx.imageSmoothingEnabled = true;
+ ctx.imageSmoothingQuality = 'high';
+ ctx.drawImage(frame, crop.x, crop.y, crop.width, crop.height, 0, 0, output.width, output.height);
+ const sx = output.width / rect.width;
+ const sy = output.height / rect.height;
+ ctx.setTransform(sx, 0, 0, sy, -rect.x * sx, -rect.y * sy);
+ drawAnnotations(ctx, list, source);
+ const image = imageDataToBitmap(ctx.getImageData(0, 0, output.width, output.height));
+ busyRef.current = true;
+ setAiMenuOpen(false);
+ const ok = await bridge
+ .exportImage(current.token, { action, selection: selected, image })
+ .catch(() => false);
+ if (!ok) busyRef.current = false;
+ },
+ [annotationSource, bridge, commitEditing],
+ );
+
+ const cancel = useCallback(() => {
+ const current = state.current.session;
+ if (current) bridge.cancel(current.token);
+ }, [bridge]);
+
+ const selectRegion = useCallback(
+ (rect: RegionRect) => {
+ const current = state.current.session;
+ if (!current) return;
+ const normalized = normalizeRegionSelection(rect, current.viewport, current.scaleFactor);
+ if (!normalized) return;
+ bridge.selectionStarted(current.token);
+ setSelection(normalized);
+ setHover(null);
+ },
+ [bridge],
+ );
+
+ const colorAt = useCallback((point: RegionPoint | null): PixelColor | null => {
+ const current = state.current.session;
+ if (!current || !point) return null;
+ const { frameData, frameSize, viewport: size } = current;
+ const rect = longResultRef.current ? state.current.selection : null;
+ if (rect && !rectContains(rect, point)) return null;
+ const x = Math.min(frameSize.width - 1, Math.max(0, Math.floor(((point.x - (rect?.x ?? 0)) * frameSize.width) / (rect?.width ?? size.width))));
+ const y = Math.min(frameSize.height - 1, Math.max(0, Math.floor(((point.y - (rect?.y ?? 0)) * frameSize.height) / (rect?.height ?? size.height))));
+ const index = (y * frameSize.width + x) * 4;
+ return { r: frameData.data[index], g: frameData.data[index + 1], b: frameData.data[index + 2] };
+ }, []);
+
+ // ── 指针 ───────────────────────────────────────────────────────────────
+
+ const localPoint = (event: { clientX: number; clientY: number }): RegionPoint => {
+ const bounds = imageEditor ? rootRef.current?.getBoundingClientRect() : null;
+ return {
+ x: Math.min(viewport.width, Math.max(0, bounds ? (event.clientX - bounds.left) * viewport.width / bounds.width : event.clientX)),
+ y: Math.min(viewport.height, Math.max(0, bounds ? (event.clientY - bounds.top) * viewport.height / bounds.height : event.clientY)),
+ };
+ };
+
+ const startEditing = (at: RegionPoint, existing: TextAnnotation | null) => {
+ const style = state.current.styles.text;
+ setSelectedId(null);
+ setEditing(
+ existing
+ ? { id: existing.id, at: existing.at, color: existing.color, size: existing.size, text: existing.text }
+ : { id: null, at, color: style.color, size: style.size, text: '' },
+ );
+ };
+
+ const onPointerDown = (event: ReactPointerEvent<HTMLDivElement>) => {
+ const s = state.current;
+ if (!s.session || busyRef.current) return;
+ if (event.button !== 0) return;
+ const point = localPoint(event);
+ if (s.aiMenuOpen) {
+ setAiMenuOpen(false);
+ return;
+ }
+ if (s.editing) {
+ commitEditing();
+ return;
+ }
+ rootRef.current?.setPointerCapture(event.pointerId);
+ const rect = s.selection;
+ if (!rect) {
+ setDrag({ kind: 'select', anchor: point, moved: false });
+ return;
+ }
+ const handle = regionHandleAt(rect, point, HANDLE_TOLERANCE);
+ if (handle && !longResultRef.current) {
+ setDrag({ kind: 'resize', start: rect, handle });
+ return;
+ }
+ const insideSelection = rectContains(rect, point);
+ if (!insideSelection) return;
+ const hit = annotationAt(s.annotations, point);
+ if (s.tool === 'text') {
+ startEditing(point, hit && hit.kind === 'text' ? hit : null);
+ return;
+ }
+ // 画笔 / 荧光笔可以直接画在已有标注上; 其它工具点中已有标注时改为选中它。
+ if (hit && s.tool !== 'pen' && s.tool !== 'marker') {
+ setSelectedId(hit.id);
+ setDrag({ kind: 'move-annotation', original: hit, origin: point, moved: false });
+ return;
+ }
+ setSelectedId(null);
+ if (s.tool === 'step') {
+ const style = s.styles.step;
+ commitAnnotations([
+ ...s.annotations,
+ { id: nextId(), kind: 'step', at: point, number: nextStepNumber(s.annotations), ...style },
+ ]);
+ return;
+ }
+ if (s.tool) {
+ const style = s.styles[s.tool];
+ const created: Annotation =
+ s.tool === 'pen' || s.tool === 'marker'
+ ? { id: nextId(), kind: s.tool, points: [point], ...style }
+ : { id: nextId(), kind: s.tool as ShapeAnnotation['kind'], from: point, to: point, ...style };
+ setDraft(created);
+ setDrag({ kind: 'draw', origin: point });
+ return;
+ }
+ if (!longResultRef.current) setDrag({ kind: 'move', start: rect, origin: point });
+ };
+
+ const onPointerMove = (event: ReactPointerEvent<HTMLDivElement>) => {
+ const s = state.current;
+ if (!s.session) return;
+ const point = localPoint(event);
+ setPointer(point);
+ state.current.pointer = point;
+ const current = s.drag;
+ if (!current) {
+ if (!s.selection) {
+ refreshHover(point);
+ requestElements(point);
+ }
+ return;
+ }
+ switch (current.kind) {
+ case 'select': {
+ const moved =
+ current.moved ||
+ Math.hypot(point.x - current.anchor.x, point.y - current.anchor.y) > DRAG_THRESHOLD;
+ if (!moved) return;
+ if (!current.moved) {
+ bridge.selectionStarted(s.session.token);
+ setDrag({ ...current, moved: true });
+ }
+ setSelection(rectFromDrag(current.anchor, point, s.session.viewport, event.shiftKey));
+ return;
+ }
+ case 'move':
+ setSelection(
+ moveRegion(current.start, point.x - current.origin.x, point.y - current.origin.y, s.session.viewport),
+ );
+ return;
+ case 'resize':
+ setSelection(resizeRegion(current.start, current.handle, point, s.session.viewport, event.shiftKey));
+ return;
+ case 'draw': {
+ const active = s.draft;
+ if (!active) return;
+ if ('points' in active) {
+ const last = active.points[active.points.length - 1];
+ if (Math.hypot(point.x - last.x, point.y - last.y) < 1.5) return;
+ setDraft({ ...active, points: [...active.points, point] });
+ } else if ('from' in active) {
+ const to = event.shiftKey ? constrainShape(active.kind, active.from, point) : point;
+ setDraft({ ...active, to });
+ }
+ return;
+ }
+ case 'move-annotation': {
+ const dx = point.x - current.origin.x;
+ const dy = point.y - current.origin.y;
+ if (!current.moved && Math.hypot(dx, dy) < 2) return;
+ if (!current.moved) setDrag({ ...current, moved: true });
+ const moved = moveAnnotation(current.original, dx, dy);
+ setAnnotations((list) => list.map((a) => (a.id === moved.id ? moved : a)));
+ return;
+ }
+ }
+ };
+
+ const onPointerUp = (event: ReactPointerEvent<HTMLDivElement>) => {
+ const s = state.current;
+ const current = s.drag;
+ if (rootRef.current?.hasPointerCapture(event.pointerId)) {
+ rootRef.current.releasePointerCapture(event.pointerId);
+ }
+ if (!current || !s.session) return;
+ setDrag(null);
+ switch (current.kind) {
+ case 'select': {
+ if (!current.moved) {
+ // 单击: 选中当前吸附的窗口 / 元素。
+ const target = s.hover?.candidates[s.hover.level];
+ if (target) selectRegion(target);
+ return;
+ }
+ const rect = s.selection;
+ if (!rect || rect.width < MIN_SELECTION || rect.height < MIN_SELECTION) {
+ setSelection(null);
+ refreshHover(localPoint(event));
+ return;
+ }
+ setSelection(normalizeRegionSelection(rect, s.session.viewport, s.session.scaleFactor));
+ return;
+ }
+ case 'move':
+ case 'resize': {
+ const rect = s.selection;
+ const normalized =
+ rect && normalizeRegionSelection(rect, s.session.viewport, s.session.scaleFactor);
+ if (normalized && normalized.width >= 1 && normalized.height >= 1) setSelection(normalized);
+ else setSelection(current.start);
+ return;
+ }
+ case 'draw': {
+ const active = s.draft;
+ setDraft(null);
+ if (active && isMeaningfulAnnotation(active)) commitAnnotations([...s.annotations, active]);
+ return;
+ }
+ case 'move-annotation': {
+ if (!current.moved) return;
+ // 拖动过程中已经改了列表; 撤销点记在拖动前。
+ const before = s.annotations.map((a) => (a.id === current.original.id ? current.original : a));
+ setUndoStack([...s.undoStack, before]);
+ setRedoStack([]);
+ return;
+ }
+ }
+ };
+
+ const onWheel = (event: ReactWheelEvent<HTMLDivElement>) => {
+ const s = state.current;
+ if (!s.session || s.selection || s.drag) return;
+ const gesture = wheelGestureRef.current;
+ const precise = isPreciseWheel(event.nativeEvent);
+ if (precise) {
+ if (event.timeStamp - gesture.last > WHEEL_GESTURE_GAP_MS) {
+ gesture.stepped = false;
+ wheelRef.current = 0;
+ }
+ gesture.last = event.timeStamp;
+ if (gesture.stepped) return;
+ }
+ wheelRef.current += event.deltaY;
+ if (Math.abs(wheelRef.current) < WHEEL_STEP) return;
+ const step = wheelRef.current < 0 ? 1 : -1;
+ wheelRef.current = 0;
+ if (precise) gesture.stepped = true;
+ // 向上滚 = 扩大到外层 (父元素 / 窗口 / 整屏), 向下滚 = 回到内层。
+ setHover((previous) =>
+ previous
+ ? {
+ ...previous,
+ level: Math.max(0, Math.min(previous.candidates.length - 1, previous.level + step)),
+ }
+ : previous,
+ );
+ };
+
+ const onDoubleClick = (event: ReactMouseEvent<HTMLDivElement>) => {
+ const s = state.current;
+ if (!s.selection || s.editing || s.captureMode !== 'image') return;
+ const point = localPoint(event);
+ const hit = annotationAt(s.annotations, point);
+ if (hit?.kind === 'text') {
+ startEditing(point, hit);
+ return;
+ }
+ if (!s.tool && rectContains(s.selection, point)) void runAction('copy');
+ };
+
+ const onContextMenu = (event: ReactMouseEvent<HTMLDivElement>) => {
+ event.preventDefault();
+ const s = state.current;
+ if (!s.session) {
+ bridge.abandon();
+ return;
+ }
+ if (s.editing) {
+ setEditing(null);
+ return;
+ }
+ if (s.aiMenuOpen) {
+ setAiMenuOpen(false);
+ return;
+ }
+ if (s.selection && !longResultRef.current) {
+ // 右键: 先退回框选 (丢弃选区与标注), 没有选区时退出截图。
+ setSelection(null);
+ setTool(null);
+ setAnnotations([]);
+ setUndoStack([]);
+ setRedoStack([]);
+ setSelectedId(null);
+ refreshHover(localPoint(event));
+ return;
+ }
+ if (!imageEditor) cancel();
+ };
+
+ // ── 键盘 ───────────────────────────────────────────────────────────────
+
+ useEffect(() => {
+ const onKeyDown = (event: KeyboardEvent) => {
+ if (liveRef.current) {
+ if (event.key === 'Escape' && !event.isComposing) {
+ event.preventDefault();
+ const token = state.current.session?.token;
+ if (token) bridge.cancel(token);
+ }
+ return;
+ }
+ const s = state.current;
+ // 页面没有会话却被看见 (异常状态): Esc 仍然要能退出。
+ if (!s.session && event.key === 'Escape') {
+ bridge.abandon();
+ return;
+ }
+ if (!s.session || busyRef.current) return;
+ const mod = isMac ? event.metaKey : event.ctrlKey;
+ const key = event.key;
+ if (s.editing) {
+ if (key === 'Escape' || (key === 'Enter' && mod)) {
+ event.preventDefault();
+ commitEditing();
+ }
+ return;
+ }
+ if (key === 'Escape') {
+ event.preventDefault();
+ if (s.aiMenuOpen) setAiMenuOpen(false);
+ else cancel();
+ return;
+ }
+ const rect = s.selection;
+ if (!rect) {
+ if (key === ' ') {
+ event.preventDefault();
+ selectRegion({ x: 0, y: 0, ...s.session.viewport });
+ } else if (key.toLowerCase() === 'r' && !mod && s.session.lastRegion) {
+ event.preventDefault();
+ selectRegion(s.session.lastRegion);
+ } else if (key.toLowerCase() === 'c' && !mod) {
+ const color = colorAt(s.pointer);
+ if (color) bridge.copyText(s.session.token, event.shiftKey ? colorRgb(color) : colorHex(color));
+ } else if (key === 'Enter') {
+ const target = s.hover?.candidates[s.hover.level];
+ if (target) selectRegion(target);
+ }
+ return;
+ }
+ if (mod && key.toLowerCase() === 'z') {
+ event.preventDefault();
+ if (event.shiftKey) redo();
+ else undo();
+ return;
+ }
+ if (mod && key.toLowerCase() === 'y') {
+ event.preventDefault();
+ redo();
+ return;
+ }
+ if (s.captureMode !== 'image' && !isRegionArrowKey(key)) return;
+ if (key === 'Enter' || (mod && key.toLowerCase() === 'c')) {
+ event.preventDefault();
+ void runAction('copy');
+ return;
+ }
+ if (mod && key.toLowerCase() === 's') {
+ event.preventDefault();
+ void runAction('save');
+ return;
+ }
+ if (mod && key.toLowerCase() === 't') {
+ event.preventDefault();
+ void runAction('pin');
+ return;
+ }
+ if ((key === 'Delete' || key === 'Backspace') && s.selectedId) {
+ event.preventDefault();
+ commitAnnotations(s.annotations.filter((a) => a.id !== s.selectedId));
+ setSelectedId(null);
+ return;
+ }
+ if (isRegionArrowKey(key)) {
+ event.preventDefault();
+ const step = event.shiftKey ? 10 : 1 / s.session.scaleFactor;
+ const selectedAnnotation = s.selectedId
+ ? s.annotations.find((a) => a.id === s.selectedId)
+ : undefined;
+ if (selectedAnnotation) {
+ const dx = key === 'ArrowLeft' ? -step : key === 'ArrowRight' ? step : 0;
+ const dy = key === 'ArrowUp' ? -step : key === 'ArrowDown' ? step : 0;
+ const moved = moveAnnotation(selectedAnnotation, dx, dy);
+ commitAnnotations(s.annotations.map((a) => (a.id === moved.id ? moved : a)));
+ return;
+ }
+ if (!longResultRef.current) setSelection(nudgeRegion(rect, key, step, s.session.viewport, event.altKey));
+ return;
+ }
+ if (!mod && !event.altKey && key.length === 1) {
+ const next = TOOL_BY_KEY[key.toLowerCase()];
+ if (next) {
+ event.preventDefault();
+ setTool((currentTool) => (currentTool === next ? null : next));
+ setSelectedId(null);
+ return;
+ }
+ if (key.toLowerCase() === 'c') {
+ const color = colorAt(s.pointer);
+ if (color) bridge.copyText(s.session.token, event.shiftKey ? colorRgb(color) : colorHex(color));
+ }
+ }
+ };
+ window.addEventListener('keydown', onKeyDown);
+ return () => window.removeEventListener('keydown', onKeyDown);
+ }, [bridge, cancel, colorAt, commitAnnotations, commitEditing, isMac, redo, runAction, selectRegion, undo]);
+
+ // 编辑文字时把焦点交给输入框。
+ useEffect(() => {
+ if (editing) textAreaRef.current?.focus();
+ }, [editing?.id, editing?.at.x, editing?.at.y]);
+
+ // 工具条按实际尺寸摆放。
+ useLayoutEffect(() => {
+ const element = toolbarRef.current;
+ if (!element) return;
+ const { offsetWidth: width, offsetHeight: height } = element;
+ if (width !== toolbarSize.width || height !== toolbarSize.height) setToolbarSize({ width, height });
+ });
+
+ // ── 样式 ───────────────────────────────────────────────────────────────
+
+ const selectedAnnotation = selectedId ? annotations.find((a) => a.id === selectedId) ?? null : null;
+ const styleTool: AnnotationTool | null = editing
+ ? 'text'
+ : selectedAnnotation
+ ? selectedAnnotation.kind
+ : tool;
+ const activeStyle: ToolStyle | null = editing
+ ? { color: editing.color, size: editing.size }
+ : selectedAnnotation
+ ? { color: selectedAnnotation.color, size: selectedAnnotation.size }
+ : tool
+ ? styles[tool]
+ : null;
+
+ const applyStyle = (patch: Partial<ToolStyle>) => {
+ if (!styleTool) return;
+ setStyles((previous) => ({ ...previous, [styleTool]: { ...previous[styleTool], ...patch } }));
+ if (editing) {
+ setEditing({ ...editing, ...patch });
+ return;
+ }
+ if (selectedAnnotation) {
+ commitAnnotations(
+ annotations.map((a) => (a.id === selectedAnnotation.id ? ({ ...a, ...patch } as Annotation) : a)),
+ );
+ }
+ };
+
+ // ── 渲染 ───────────────────────────────────────────────────────────────
+
+ const highlight = selection ?? (hover ? hover.candidates[hover.level] ?? null : null);
+ const scale = session?.scaleFactor ?? 1;
+ const dragging = drag !== null && drag.kind !== 'move-annotation' && drag.kind !== 'draw';
+
+ let cursor = 'crosshair';
+ if (pointer && selection && !drag) {
+ const handle = longResult ? null : regionHandleAt(selection, pointer, HANDLE_TOLERANCE);
+ if (handle) cursor = HANDLE_CURSORS[handle];
+ else if (rectContains(selection, pointer)) {
+ if (tool === 'text') cursor = 'text';
+ else if (annotationAt(annotations, pointer)) cursor = 'move';
+ else cursor = tool ? 'crosshair' : longResult ? 'default' : 'move';
+ } else cursor = 'default';
+ } else if (drag?.kind === 'resize') cursor = HANDLE_CURSORS[drag.handle];
+ else if (drag?.kind === 'move' || drag?.kind === 'move-annotation') cursor = 'move';
+
+ const showMagnifier =
+ !!session && !longResult && !!pointer && !overToolbar && !editing && (!selection || dragging) && drag?.kind !== 'move';
+
+ let toolbarStyle: CSSProperties | null = null;
+
+ if (isSelected && selection && !dragging) {
+ // 工具条只放在安全区内: 不被刘海遮住, 也不压在 Dock / 任务栏上; 选区本身可以覆盖它们。
+ const bottom = selection.y + selection.height;
+ const safeBottom = safe.y + safe.height;
+ const extra = styleTool ? toolbarSize.height + GAP : 0;
+ const below = bottom + GAP + toolbarSize.height + extra <= safeBottom;
+ const above = selection.y - GAP - toolbarSize.height - extra >= safe.y;
+ const top = below
+ ? bottom + GAP
+ : above
+ ? selection.y - GAP - toolbarSize.height
+ : Math.min(bottom, safeBottom) - GAP - toolbarSize.height;
+ const position = clampIntoArea({ x: selection.x + selection.width - toolbarSize.width, y: top }, toolbarSize, safe);
+ toolbarStyle = { left: position.x, top: position.y };
+ }
+
+ const sizeLabel = longResult ? `${longResult.image.width} × ${longResult.image.height}` : highlight
+ ? `${Math.round(highlight.width * scale)} × ${Math.round(highlight.height * scale)}`
+ : null;
+ const sizeLabelTop = highlight
+ ? highlight.y - 28 >= safe.y ? highlight.y - 28 : Math.max(highlight.y, safe.y) + 6
+ : 0;
+
+ const editingBounds = editing
+ ? textBounds({ id: '', kind: 'text', at: editing.at, text: editing.text || ' ', color: editing.color, size: editing.size })
+ : null;
+
+ async function startLive(mode: RegionCaptureMode) {
+ if (!session || !selection || busyRef.current) return;
+ busyRef.current = true;
+ setLiveError(false);
+ try {
+ const begin = await bridge.startLive(session.token, mode, selection);
+ if (state.current.session?.token !== session.token) return;
+ if (begin) { liveRef.current = true; setLive(begin); }
+ else setLiveError(true);
+ } catch { setLiveError(true); }
+ finally { busyRef.current = false; }
+ }
+
+ async function finishScroll(image: RegionScreenshotBitmap) {
+ if (!session || !live) return;
+ if (!await bridge.restoreEditor(session.token, image)) throw new Error('Screenshot editor unavailable');
+ }
+
+ if (live && session) return live.mode === 'scroll'
+ ? <ScrollCaptureOverlay begin={live} token={session.token} bridge={bridge} onEdit={finishScroll} />
+ : <LiveCapturePanel begin={live} token={session.token} bridge={bridge} />;
+
+ const toolbar = (imageEditor || toolbarStyle) && (imageEditor || activeDisplay) && (
+ <div
+ className={imageEditor ? "flex flex-col items-start gap-2" : "absolute flex flex-col items-end gap-2"}
+ style={imageEditor ? undefined : toolbarStyle ?? undefined}
+ onPointerEnter={() => setOverToolbar(true)}
+ onPointerLeave={() => setOverToolbar(false)}
+ >
+ {captureMode === 'image' ? <ScreenshotToolbar
+ ref={toolbarRef}
+ tool={tool}
+ canUndo={undoStack.length > 0}
+ canRedo={redoStack.length > 0}
+ shortcutMod={modLabel}
+ onTool={(next) => {
+ commitEditing();
+ setSelectedId(null);
+ setTool((current) => (current === next ? null : next));
+ }}
+ onUndo={undo}
+ onRedo={redo}
+ onAction={(action) => void runAction(action)}
+ onCancel={cancel}
+ /> : captureMode === 'video' ? <div ref={toolbarRef} className="pointer-events-auto flex w-[360px] max-w-screen flex-col gap-3 rounded-xl border border-[var(--border-default)] bg-[var(--surface-elevated)] p-3 text-12 text-[var(--text-primary)]" onPointerDown={(event) => event.stopPropagation()}>
+ <div role="group" aria-label={t('regionScreenshot.live.format')} className="flex items-center gap-1">
+ <span className="mr-auto text-[var(--text-secondary)]">{t('regionScreenshot.live.format')}</span>
+ {(['video', 'gif'] as const).map((format) => <Button key={format} size="xs" variant="secondary" tone={recordingFormat === format ? 'default' : 'quiet'} aria-pressed={recordingFormat === format} onClick={() => setRecordingFormat(format)}>{format === 'gif' ? 'GIF' : t('regionScreenshot.live.videoFormat')}</Button>)}
+ </div>
+ <p className="text-[var(--text-secondary)]">{t('regionScreenshot.live.prepareHint')}</p>
+ <div className="flex justify-end gap-2">
+ <Button size="xs" variant="secondary" tone="quiet" onClick={cancel}>{t('regionScreenshot.cancel')}</Button>
+ <Button size="xs" variant="cta" onClick={() => void startLive(recordingFormat)}>{t('regionScreenshot.live.start')}</Button>
+ </div>
+ </div> : <div ref={toolbarRef} className="pointer-events-auto flex items-center gap-2 rounded-xl border border-[var(--border-default)] bg-[var(--surface-elevated)] p-1" onPointerDown={(event) => event.stopPropagation()}>
+ <Button size="xs" variant="cta" onClick={() => void startLive(captureMode)}>{t(captureMode === 'scroll' ? 'regionScreenshot.live.startScroll' : 'regionScreenshot.live.start')}</Button>
+ <Button size="xs" variant="secondary" tone="quiet" onClick={cancel}>{t('regionScreenshot.cancel')}</Button>
+ </div>}
+ {liveError && <p role="alert" className="mt-1 rounded-xl bg-[var(--surface-elevated)] p-2 text-12 text-[var(--text-primary)]">{t('regionScreenshot.live.noRoom')}</p>}
+ {captureMode === 'image' && styleTool && activeStyle && (
+ <ScreenshotStyleBar
+ tool={styleTool}
+ color={activeStyle.color}
+ size={activeStyle.size}
+ onColor={(color) => applyStyle({ color })}
+ onSize={(size) => applyStyle({ size })}
+ />
+ )}
+ </div>
+ );
+
+ const canvasContent = (
+ <div
+ ref={rootRef}
+ className={imageEditor ? "relative h-full w-full select-none overflow-hidden" : "fixed inset-0 select-none overflow-hidden"}
+ style={{ cursor, background: imageEditor ? undefined : SCREENSHOT_OVERLAY.backdrop }}
+ onPointerEnter={() => {
+ if (!state.current.session) return;
+ setActiveDisplay(true);
+ if (!imageEditor) window.focus();
+ }}
+ onPointerDown={onPointerDown}
+ onPointerMove={onPointerMove}
+ onPointerUp={onPointerUp}
+ onPointerLeave={() => {
+ // 指针移到另一块屏: 这块屏不再显示放大镜和吸附高亮。
+ if (!imageEditor) setActiveDisplay(false);
+ setAiMenuOpen(false);
+ setPointer(null);
+ if (!state.current.selection && !state.current.drag) setHover(null);
+ }}
+ onWheel={onWheel}
+ onDoubleClick={onDoubleClick}
+ onContextMenu={onContextMenu}
+ >
+ <canvas ref={frameRef} className={longResult ? 'absolute block' : 'absolute inset-0 block h-full w-full'} style={longResult && selection ? { left: selection.x, top: selection.y, width: selection.width, height: selection.height } : undefined} />
+ <canvas ref={annotationCanvasRef} className="pointer-events-none absolute inset-0 block h-full w-full" />
+ {session && !imageEditor &&
+ (highlight ? (
+ <div
+ className="pointer-events-none absolute"
+ style={{
+ left: highlight.x,
+ top: highlight.y,
+ width: highlight.width,
+ height: highlight.height,
+ outline: `${selection ? 1 : 2}px solid ${SCREENSHOT_OVERLAY.edge}`,
+ boxShadow: `0 0 0 1px ${SCREENSHOT_OVERLAY.edgeOuter}, 0 0 0 100000px ${SCREENSHOT_OVERLAY.shade}`,
+ }}
+ />
+ ) : (
+ <div className="pointer-events-none absolute inset-0" style={{ background: SCREENSHOT_OVERLAY.shade }} />
+ ))}
+ {session && !longResult && isSelected && selection && !dragging &&
+ HANDLES.map((handle) => {
+ const p = handlePosition(selection, handle);
+ return (
+ <span
+ key={handle}
+ className="pointer-events-none absolute h-2 w-2 rounded-full"
+ style={{
+ left: p.x - 4,
+ top: p.y - 4,
+ background: SCREENSHOT_OVERLAY.edge,
+ boxShadow: `0 0 0 1px ${SCREENSHOT_OVERLAY.edgeOuter}`,
+ }}
+ />
+ );
+ })}
+ {selectedAnnotation && (() => {
+ const b = annotationBounds(selectedAnnotation);
+ return (
+ <div
+ className="pointer-events-none absolute"
+ style={{
+ left: b.x - 4,
+ top: b.y - 4,
+ width: b.width + 8,
+ height: b.height + 8,
+ outline: `1px dashed ${SCREENSHOT_OVERLAY.edge}`,
+ boxShadow: `0 0 0 1px ${SCREENSHOT_OVERLAY.edgeOuter}`,
+ }}
+ />
+ );
+ })()}
+ {session && !imageEditor && sizeLabel && highlight && (
+ <div
+ className="pointer-events-none absolute rounded-lg border border-[var(--border-default)] bg-[var(--surface-elevated)] px-2 py-0.5 text-12 tabular-nums text-[var(--text-primary)]"
+ style={{ left: Math.max(safe.x, Math.min(highlight.x, safe.x + safe.width - 120)), top: sizeLabelTop }}
+ >
+ {sizeLabel}
+ </div>
+ )}
+ {session && activeDisplay && !selection && !drag && (
+ <div style={{ left: safe.x + safe.width / 2, top: safe.y + 64 }} className="pointer-events-none absolute -translate-x-1/2 whitespace-nowrap rounded-full border border-[var(--border-default)] bg-[var(--surface-elevated)] px-3.5 py-1.5 text-12 text-[var(--text-secondary)]">
+ {session.lastRegion ? t('regionScreenshot.hintWithLast') : t('regionScreenshot.hint')}
+ </div>
+ )}
+ {editing && editingBounds && (
+ <textarea
+ ref={textAreaRef}
+ value={editing.text}
+ spellCheck={false}
+ onChange={(event) => setEditing({ ...editing, text: event.target.value })}
+ onPointerDown={(event) => event.stopPropagation()}
+ onContextMenu={(event) => event.stopPropagation()}
+ className="absolute resize-none overflow-hidden border-0 bg-transparent p-0 outline-none"
+ style={{
+ left: editing.at.x,
+ top: editing.at.y,
+ width: Math.max(24, editingBounds.width + TEXT_SIZE[editing.size]),
+ height: editingBounds.height,
+ font: textFont(editing.size),
+ lineHeight: TEXT_LINE_HEIGHT,
+ color: SCREENSHOT_INK[editing.color],
+ caretColor: SCREENSHOT_INK[editing.color],
+ outline: `1px dashed ${SCREENSHOT_OVERLAY.edge}`,
+ outlineOffset: 3,
+ }}
+ />
+ )}
+ {session && !imageEditor && activeDisplay && <div className="absolute z-20 w-max -translate-x-1/2" style={{ left: modeBarCenter ?? safe.x + safe.width / 2, top: safe.y + 12, maxWidth: safe.width - 24 }} onPointerEnter={() => setOverToolbar(true)} onPointerLeave={() => setOverToolbar(false)}>
+ <ScreenshotModeBar mode={captureMode} finished={!!longResult} canAsk={isSelected && !dragging} aiMenuOpen={aiMenuOpen}
+ area={safe} onPositionChange={setModeBarCenter}
+ onMode={(mode) => { commitEditing(); setCaptureMode(mode); setTool(null); setSelectedId(null); setAiMenuOpen(false); setLiveError(false); }}
+ onToggleAiMenu={() => setAiMenuOpen((open) => !open)} onAction={(action) => void runAction(action)} />
+ </div>}
+ {!imageEditor && toolbar}
+
+ {showMagnifier && pointer && session && (
+ <Magnifier
+ frame={frameRef.current}
+ frameSize={session.frameSize}
+ point={pointer}
+ viewport={viewport}
+ bounds={safe}
+ color={colorAt(pointer)}
+ scaleFactor={session.scaleFactor}
+ />
+ )}
+ </div>
+ );
+ return imageEditor ? <ScreenshotEditorViewport key={session?.token ?? 'empty'} image={session?.frameSize ?? null} tools={toolbar} onAction={(action) => void runAction(action)}
+ onMinimize={() => { if (session) window.regionScreenshotEditor?.minimize(session.token); }}
+ onClose={() => { if (session) bridge.cancel(session.token); }}
+ >{canvasContent}</ScreenshotEditorViewport> : canvasContent;
+}
diff --git a/apps/desktop/src/renderer/features/region-screenshot/ScreenshotEditorViewport.tsx b/apps/desktop/src/renderer/features/region-screenshot/ScreenshotEditorViewport.tsx
new file mode 100644
index 0000000000..b909a02e36
--- /dev/null
+++ b/apps/desktop/src/renderer/features/region-screenshot/ScreenshotEditorViewport.tsx
@@ -0,0 +1,93 @@
+import { useEffect, useLayoutEffect, useRef, useState, type ReactNode } from 'react';
+import { useTranslation } from 'react-i18next';
+import { Minus, X } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import type { RegionSize } from '../../../shared/regionScreenshot';
+import { isPreciseWheel, pinchZoomFactor } from './trackpad';
+
+/** Image coordinates stay unchanged: zoom/scroll only transform the editing viewport. */
+export function ScreenshotEditorViewport({ image, tools, children, onAction, onMinimize, onClose }: {
+ image: RegionSize | null; tools: ReactNode; children: ReactNode;
+ onAction: (action: 'ask' | 'translate' | 'explain' | 'extract') => void;
+ onMinimize: () => void;
+ onClose: () => void;
+}) {
+ const { t } = useTranslation();
+ const scrollRef = useRef<HTMLDivElement>(null);
+ const contentRef = useRef<HTMLDivElement>(null);
+ /** 同一帧内连续的捏合事件按最新倍率叠乘, 不读渲染前的旧值。 */
+ const scaleRef = useRef(1);
+ const [size, setSize] = useState({ width: 900, height: 600 });
+ const [zoom, setZoom] = useState<number | 'width' | 'fit'>('width');
+ useLayoutEffect(() => {
+ const node = scrollRef.current;
+ if (!node) return;
+ const observer = new ResizeObserver(() => setSize({ width: node.clientWidth, height: node.clientHeight }));
+ observer.observe(node);
+ return () => observer.disconnect();
+ }, []);
+ const scale = !image ? 1 : typeof zoom === 'number' ? zoom : Math.max(0.01, Math.min(
+ 1, (size.width - 32) / image.width, zoom === 'fit' ? (size.height - 32) / image.height : Infinity,
+ ));
+ scaleRef.current = scale;
+ /** `anchor` 是视口内的客户端坐标; 缩放后它下面仍是同一个图像像素 (缺省为视口中心)。 */
+ const changeZoom = (next: number, anchor?: { x: number; y: number }) => {
+ const node = scrollRef.current;
+ const content = contentRef.current;
+ const ratio = Math.max(0.01, Math.min(4, next));
+ const before = scaleRef.current;
+ scaleRef.current = ratio;
+ setZoom(ratio);
+ if (!node || !content) return;
+ const viewport = node.getBoundingClientRect();
+ const point = anchor ?? { x: viewport.left + node.clientWidth / 2, y: viewport.top + node.clientHeight / 2 };
+ const rect = content.getBoundingClientRect();
+ const imageX = (point.x - rect.left) / before, imageY = (point.y - rect.top) / before;
+ requestAnimationFrame(() => {
+ const moved = content.getBoundingClientRect();
+ node.scrollLeft += moved.left + imageX * ratio - point.x;
+ node.scrollTop += moved.top + imageY * ratio - point.y;
+ });
+ };
+ useEffect(() => {
+ const node = scrollRef.current;
+ if (!node) return;
+ const wheel = (event: WheelEvent) => {
+ if (!event.ctrlKey && !event.metaKey) return;
+ event.preventDefault();
+ // 触控板捏合 (ctrlKey) 与 ⌘ + 双指滑动连续缩放; 鼠标滚轮每格一级。以指针为中心。
+ const factor = isPreciseWheel(event) ? pinchZoomFactor(event.deltaY) : event.deltaY < 0 ? 1.1 : 1 / 1.1;
+ changeZoom(scaleRef.current * factor, { x: event.clientX, y: event.clientY });
+ };
+ node.addEventListener('wheel', wheel, { passive: false });
+ return () => node.removeEventListener('wheel', wheel);
+ });
+ return <div className="flex h-screen flex-col bg-[var(--surface)] text-[var(--text-primary)]">
+ <div className="z-10 shrink-0 border-b border-[var(--border-default)] p-2">
+ <div className="flex flex-wrap items-center gap-1 pb-2 [-webkit-app-region:drag] [&_button]:[-webkit-app-region:no-drag]">
+ <Button size="xs" variant="secondary" aria-label={t('remoteDesktop.zoomOut')} onClick={() => changeZoom(scale / 1.2)}>−</Button>
+ <span className="w-12 text-center text-12 tabular-nums" aria-live="polite">{Math.round(scale * 100)}%</span>
+ <Button size="xs" variant="secondary" aria-label={t('remoteDesktop.zoomIn')} onClick={() => changeZoom(scale * 1.2)}>+</Button>
+ <Button size="xs" variant="secondary" tone="quiet" onClick={() => setZoom('width')}>{t('regionScreenshot.editor.fitWidth')}</Button>
+ <Button size="xs" variant="secondary" tone="quiet" onClick={() => setZoom('fit')}>{t('remoteDesktop.fit')}</Button>
+ <Button size="xs" variant="secondary" tone="quiet" onClick={() => changeZoom(1)}>{t('remoteDesktop.actualSize')}</Button>
+ <span className="min-w-8 flex-1" />
+ <span className="text-12 tabular-nums text-[var(--text-secondary)]">{image && `${image.width} × ${image.height}`}</span>
+ <details className="relative text-12 [-webkit-app-region:no-drag]">
+ <summary className="cursor-pointer rounded-full px-3 py-1.5">Cindy</summary>
+ <div className="absolute right-0 top-full z-20 flex min-w-40 flex-col rounded-xl border border-[var(--border-default)] bg-[var(--surface-elevated)] p-1">
+ {(['ask', 'translate', 'explain', 'extract'] as const).map((action) => <Button key={action} size="xs" variant="secondary" tone="quiet" onClick={() => onAction(action)}>{t('regionScreenshot.ai.' + action)}</Button>)}
+ </div>
+ </details>
+ <Button size="xs" variant="secondary" tone="quiet" className="w-7 px-0" aria-label={t('titleBar.minimize')} onClick={onMinimize}><Minus size={14} /></Button>
+ <Button size="xs" variant="secondary" tone="quiet" className="w-7 px-0" aria-label={t('titleBar.close')} onClick={onClose}><X size={14} /></Button>
+ </div>
+ {image && tools}
+ </div>
+ <div ref={scrollRef} className="min-h-0 flex-1 overflow-auto p-4" tabIndex={0} aria-label={t('regionScreenshot.live.edit')}>
+ {image ? <div ref={contentRef} className="relative mx-auto" style={{ width: image.width * scale, height: image.height * scale }}>
+ <div className="absolute left-0 top-0 origin-top-left" style={{ width: image.width, height: image.height, transform: `scale(${scale})` }}>{children}</div>
+ </div> : <p role="status" className="text-13 text-[var(--text-secondary)]">{t('regionScreenshot.editor.loading')}</p>}
+ </div>
+ </div>;
+}
diff --git a/apps/desktop/src/renderer/features/region-screenshot/ScreenshotErrorBoundary.tsx b/apps/desktop/src/renderer/features/region-screenshot/ScreenshotErrorBoundary.tsx
new file mode 100644
index 0000000000..843fe7af50
--- /dev/null
+++ b/apps/desktop/src/renderer/features/region-screenshot/ScreenshotErrorBoundary.tsx
@@ -0,0 +1,22 @@
+import { Component, type ReactNode } from 'react';
+import { createLogger } from '@/lib/logger';
+
+const log = createLogger('screenshot-error-boundary');
+
+/** 系统浮层不能用主应用崩溃页挡住桌面;渲染失败立即交还屏幕。 */
+export class ScreenshotErrorBoundary extends Component<
+ { children: ReactNode; onFailure: () => void },
+ { failed: boolean }
+> {
+ state = { failed: false };
+ static getDerivedStateFromError() {
+ return { failed: true };
+ }
+ componentDidCatch(error: unknown) {
+ log.warn('screenshot render failed', { error });
+ this.props.onFailure();
+ }
+ render() {
+ return this.state.failed ? null : this.props.children;
+ }
+}
diff --git a/apps/desktop/src/renderer/features/region-screenshot/ScreenshotToolbar.tsx b/apps/desktop/src/renderer/features/region-screenshot/ScreenshotToolbar.tsx
new file mode 100644
index 0000000000..78b3ba0f10
--- /dev/null
+++ b/apps/desktop/src/renderer/features/region-screenshot/ScreenshotToolbar.tsx
@@ -0,0 +1,322 @@
+import { forwardRef, useRef, type ReactNode } from 'react';
+import { useTranslation } from 'react-i18next';
+import {
+ Check,
+ Circle,
+ Download,
+ Droplets,
+ Grid3x3,
+ GripVertical,
+ Highlighter,
+ Languages,
+ Lightbulb,
+ ListOrdered,
+ MessageCircleQuestion,
+ Minus,
+ MoveUpRight,
+ Pencil,
+ Pin,
+ Redo2,
+ ScanText,
+ Sparkles,
+ Square,
+ Type,
+ Undo2,
+ X,
+} from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import { Tip } from '@/components/ui/tooltip';
+import { cn } from '@/lib/utils';
+import '@/components/ui/button.css';
+import type { RegionScreenshotAiAction } from '../../../shared/regionScreenshot';
+import type { RegionCaptureMode } from '../../../shared/regionCapture';
+import {
+ ANNOTATION_COLORS,
+ ANNOTATION_TOOLS,
+ type AnnotationSize,
+ type AnnotationTool,
+} from './annotations';
+import { SCREENSHOT_INK, type ScreenshotInk } from './screenshotColors';
+
+export const TOOL_SHORTCUTS: Record<AnnotationTool, string> = {
+ rect: 'R',
+ ellipse: 'E',
+ line: 'L',
+ arrow: 'A',
+ pen: 'P',
+ marker: 'M',
+ text: 'T',
+ mosaic: 'X',
+ blur: 'B',
+ step: 'N',
+};
+
+const TOOL_ICONS: Record<AnnotationTool, typeof Square> = {
+ rect: Square,
+ ellipse: Circle,
+ line: Minus,
+ arrow: MoveUpRight,
+ pen: Pencil,
+ marker: Highlighter,
+ text: Type,
+ mosaic: Grid3x3,
+ blur: Droplets,
+ step: ListOrdered,
+};
+
+const AI_ICONS: Record<RegionScreenshotAiAction, typeof Square> = {
+ ask: MessageCircleQuestion,
+ translate: Languages,
+ explain: Lightbulb,
+ extract: ScanText,
+};
+
+function IconButton({
+ label,
+ active = false,
+ disabled = false,
+ onClick,
+ children,
+}: {
+ label: string;
+ active?: boolean;
+ disabled?: boolean;
+ onClick: () => void;
+ children: ReactNode;
+}) {
+ return (
+ <Tip text={label} side="top" delay={300}>
+ <button
+ type="button"
+ aria-label={label}
+ aria-pressed={active || undefined}
+ aria-disabled={disabled || undefined}
+ // 鼠标点按钮不把焦点留在按钮上, 快捷键与文字输入照常交给浮层。
+ onMouseDown={(event) => event.preventDefault()}
+ onClick={disabled ? undefined : onClick}
+ className={cn(
+ 'cindy-button-frame inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-full transition-colors',
+ 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--focus-ring)]',
+ active
+ ? '[--button-face-bg:var(--surface-chip)] text-[var(--text-primary)]'
+ : 'text-[var(--text-secondary)]',
+ disabled
+ ? 'cursor-default opacity-60'
+ : 'hover:text-[var(--text-primary)] hover:[--button-face-bg:var(--surface-hover)]',
+ )}
+ >
+ {children}
+ </button>
+ </Tip>
+ );
+}
+
+const Divider = () => <span className="mx-1 h-4 w-px shrink-0 bg-[var(--border-default)]" />;
+
+export interface ScreenshotToolbarProps {
+ tool: AnnotationTool | null;
+ canUndo: boolean;
+ canRedo: boolean;
+ shortcutMod: string;
+ onTool: (tool: AnnotationTool) => void;
+ onUndo: () => void;
+ onRedo: () => void;
+ onAction: (action: 'copy' | 'save' | 'pin' | RegionScreenshotAiAction) => void;
+ onCancel: () => void;
+}
+
+/** 选区下方的工具条: 标注工具 | 撤销重做 | 贴图 保存 | 退出 复制。 */
+export const ScreenshotToolbar = forwardRef<HTMLDivElement, ScreenshotToolbarProps>(
+ function ScreenshotToolbar(props, ref) {
+ const { t } = useTranslation();
+ const mod = props.shortcutMod;
+ return (
+ <div
+ ref={ref}
+ className="pointer-events-auto relative flex items-center gap-0.5 rounded-xl border border-[var(--border-default)] bg-[var(--surface-elevated)] p-1"
+ onPointerDown={(event) => event.stopPropagation()}
+ onContextMenu={(event) => event.stopPropagation()}
+ onDoubleClick={(event) => event.stopPropagation()}
+ >
+ {ANNOTATION_TOOLS.map((tool) => {
+ const Icon = TOOL_ICONS[tool];
+ return (
+ <IconButton
+ key={tool}
+ label={`${t(`regionScreenshot.tools.${tool}`)} (${TOOL_SHORTCUTS[tool]})`}
+ active={props.tool === tool}
+ onClick={() => props.onTool(tool)}
+ >
+ <Icon size={15} strokeWidth={tool === 'step' ? 2 : 1.75} />
+ </IconButton>
+ );
+ })}
+ <Divider />
+ <IconButton label={`${t('regionScreenshot.undo')} (${mod}Z)`} disabled={!props.canUndo} onClick={props.onUndo}>
+ <Undo2 size={15} />
+ </IconButton>
+ <IconButton label={`${t('regionScreenshot.redo')} (${mod}⇧Z)`} disabled={!props.canRedo} onClick={props.onRedo}>
+ <Redo2 size={15} />
+ </IconButton>
+ <Divider />
+ <IconButton label={`${t('regionScreenshot.pinToScreen')} (${mod}T)`} onClick={() => props.onAction('pin')}>
+ <Pin size={15} />
+ </IconButton>
+ <IconButton label={`${t('regionScreenshot.save')} (${mod}S)`} onClick={() => props.onAction('save')}>
+ <Download size={15} />
+ </IconButton>
+ <Divider />
+ <IconButton label={`${t('regionScreenshot.cancel')} (Esc)`} onClick={props.onCancel}>
+ <X size={15} />
+ </IconButton>
+ <Tip text={t('regionScreenshot.live.finish')} side="top" delay={300}>
+ <Button
+ variant="cta"
+ size="xs"
+ className="ml-1 w-7 shrink-0 px-0"
+ aria-label={t('regionScreenshot.live.finish')}
+ onMouseDown={(event) => event.preventDefault()}
+ onClick={() => props.onAction('copy')}
+ >
+ <Check size={16} aria-hidden="true" />
+ </Button>
+ </Tip>
+ </div>
+ );
+ },
+);
+
+export type ScreenshotMode = 'image' | Exclude<RegionCaptureMode, 'gif'>;
+
+/** Screen-top mode switcher stays available before and after selecting a region. */
+export function ScreenshotModeBar(props: {
+ mode: ScreenshotMode;
+ onMode: (mode: ScreenshotMode) => void;
+ finished: boolean;
+ canAsk: boolean;
+ aiMenuOpen: boolean;
+ onToggleAiMenu: () => void;
+ onAction: (action: RegionScreenshotAiAction) => void;
+ /** 可拖动的横向范围 (本显示器 DIP 的安全区), 不拖进刘海或屏幕外。 */
+ area: { x: number; width: number };
+ onPositionChange: (center: number) => void;
+}) {
+ const { t } = useTranslation();
+ const drag = useRef<{ pointerId: number; x: number; left: number; width: number } | null>(null);
+ const moveTo = (left: number, width: number) => {
+ const bounded = Math.max(props.area.x + 8, Math.min(props.area.x + props.area.width - width - 8, left));
+ props.onPositionChange(bounded + width / 2);
+ };
+ return <div className="pointer-events-auto relative flex flex-wrap items-center justify-center gap-1 rounded-xl border border-[var(--border-default)] bg-[var(--surface-elevated)] p-1"
+ onPointerDown={(event) => event.stopPropagation()} onContextMenu={(event) => event.stopPropagation()} onDoubleClick={(event) => event.stopPropagation()}>
+ <button type="button" aria-label={t('regionScreenshot.moveToolbar')} title={t('regionScreenshot.moveToolbar')}
+ className="inline-flex h-7 w-6 shrink-0 touch-none cursor-grab items-center justify-center rounded-full text-[var(--text-tertiary)] hover:text-[var(--text-primary)] active:cursor-grabbing focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--focus-ring)]"
+ onPointerDown={(event) => {
+ event.stopPropagation();
+ if (event.button !== 0) return;
+ event.preventDefault();
+ const bounds = event.currentTarget.parentElement!.getBoundingClientRect();
+ drag.current = { pointerId: event.pointerId, x: event.clientX, left: bounds.left, width: bounds.width };
+ event.currentTarget.setPointerCapture(event.pointerId);
+ }}
+ onPointerMove={(event) => {
+ event.stopPropagation();
+ const current = drag.current;
+ if (current?.pointerId === event.pointerId) moveTo(current.left + event.clientX - current.x, current.width);
+ }}
+ onPointerUp={(event) => {
+ event.stopPropagation();
+ if (drag.current?.pointerId !== event.pointerId) return;
+ drag.current = null;
+ event.currentTarget.releasePointerCapture(event.pointerId);
+ }}
+ onPointerCancel={() => { drag.current = null; }} onLostPointerCapture={() => { drag.current = null; }}
+ onKeyDown={(event) => {
+ if (event.key !== 'ArrowLeft' && event.key !== 'ArrowRight') return;
+ event.preventDefault(); event.stopPropagation();
+ const bounds = event.currentTarget.parentElement!.getBoundingClientRect();
+ moveTo(bounds.left + (event.key === 'ArrowLeft' ? -1 : 1) * (event.shiftKey ? 40 : 10), bounds.width);
+ }}><GripVertical size={14} /></button>
+ {(['image', 'scroll', 'video'] as const).filter((mode) => !props.finished || mode === 'image').map((mode) => <Button key={mode} size="xs" variant="secondary" tone={props.mode === mode ? 'default' : 'quiet'} aria-pressed={props.mode === mode}
+ onMouseDown={(event) => event.preventDefault()} onClick={() => props.onMode(mode)}>{t(mode === 'image' ? 'regionScreenshot.live.image' : 'regionScreenshot.live.' + mode)}</Button>)}
+ <Divider />
+ <div className="relative">
+ <Button size="xs" variant="secondary" tone={props.aiMenuOpen ? 'default' : 'quiet'} disabled={!props.canAsk} aria-label={t('regionScreenshot.cindy')} aria-expanded={props.aiMenuOpen}
+ onMouseDown={(event) => event.preventDefault()} onClick={props.onToggleAiMenu}><Sparkles size={14} />Cindy</Button>
+ {props.aiMenuOpen && <div role="menu" className="absolute right-0 top-full z-10 mt-2 flex min-w-[168px] flex-col rounded-xl border border-[var(--border-default)] bg-[var(--surface-elevated)] p-1">
+ {(['ask', 'translate', 'explain', 'extract'] as const).map((action) => {
+ const Icon = AI_ICONS[action];
+ return <button key={action} type="button" role="menuitem" onMouseDown={(event) => event.preventDefault()} onClick={() => props.onAction(action)}
+ className="flex h-8 items-center gap-2 rounded-lg px-2.5 text-left text-13 text-[var(--text-primary)] hover:bg-[var(--surface-hover)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--focus-ring)]">
+ <Icon size={15} className="shrink-0 text-[var(--text-secondary)]" /><span className="flex-1">{t('regionScreenshot.ai.' + action)}</span>
+ </button>;
+ })}
+ </div>}
+ </div>
+ </div>;
+}
+
+/** 当前工具 (或选中标注) 的颜色与粗细; 马赛克 / 模糊只有强度。 */
+export function ScreenshotStyleBar({
+ tool,
+ color,
+ size,
+ onColor,
+ onSize,
+}: {
+ tool: AnnotationTool;
+ color: ScreenshotInk;
+ size: AnnotationSize;
+ onColor: (color: ScreenshotInk) => void;
+ onSize: (size: AnnotationSize) => void;
+}) {
+ const { t } = useTranslation();
+ const showColors = tool !== 'mosaic' && tool !== 'blur';
+ const sizeKey = tool === 'text' ? 'text' : tool === 'mosaic' || tool === 'blur' ? 'strength' : 'stroke';
+ return (
+ <div
+ className="pointer-events-auto flex items-center gap-1 rounded-xl border border-[var(--border-default)] bg-[var(--surface-elevated)] p-1"
+ onPointerDown={(event) => event.stopPropagation()}
+ onContextMenu={(event) => event.stopPropagation()}
+ >
+ {([0, 1, 2] as const).map((value) => (
+ <IconButton
+ key={value}
+ label={t(`regionScreenshot.size.${sizeKey}.${value}`)}
+ active={size === value}
+ onClick={() => onSize(value)}
+ >
+ <span
+ className="rounded-full bg-current"
+ style={{ width: 4 + value * 3, height: 4 + value * 3 }}
+ />
+ </IconButton>
+ ))}
+ {showColors && <Divider />}
+ {showColors &&
+ ANNOTATION_COLORS.map((value) => (
+ <Tip key={value} text={t(`regionScreenshot.colors.${value}`)} side="top" delay={300}>
+ <button
+ type="button"
+ aria-label={t(`regionScreenshot.colors.${value}`)}
+ aria-pressed={color === value || undefined}
+ onMouseDown={(event) => event.preventDefault()}
+ onClick={() => onColor(value)}
+ className={cn(
+ 'inline-flex h-7 w-7 items-center justify-center rounded-full',
+ 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--focus-ring)]',
+ color === value ? 'bg-[var(--surface-chip)]' : 'hover:bg-[var(--surface-hover)]',
+ )}
+ >
+ {/* 色块是墨水本身 (用户内容色); 细边框让白 / 黑色块在两种模式下都看得清。 */}
+ <span
+ className="h-4 w-4 rounded-full border border-[var(--border-default)]"
+ style={{ background: SCREENSHOT_INK[value] }}
+ />
+ </button>
+ </Tip>
+ ))}
+ </div>
+ );
+}
diff --git a/apps/desktop/src/renderer/features/region-screenshot/ScrollCaptureOverlay.tsx b/apps/desktop/src/renderer/features/region-screenshot/ScrollCaptureOverlay.tsx
new file mode 100644
index 0000000000..49a590b6a2
--- /dev/null
+++ b/apps/desktop/src/renderer/features/region-screenshot/ScrollCaptureOverlay.tsx
@@ -0,0 +1,212 @@
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { Check, Download, Pencil, X } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import { Button } from '@/components/ui/button';
+import { Tip } from '@/components/ui/tooltip';
+import { useReducedMotion } from '@/hooks/useReducedMotion';
+import { ScrollCapture } from '../../../shared/scrollCapture';
+import type { RegionCaptureBegin } from '../../../shared/regionCapture';
+import type { RegionScreenshotBitmap } from '../../../shared/regionScreenshot';
+import { bitmapToImageData, type RegionScreenshotOverlayBridge } from './bridge';
+
+/** The selection stays over the source app; only its thumbnail/actions take input. */
+export function ScrollCaptureOverlay({ begin, token, bridge, onEdit }: {
+ begin: RegionCaptureBegin;
+ token: string;
+ bridge: RegionScreenshotOverlayBridge;
+ onEdit(image: RegionScreenshotBitmap): Promise<void>;
+}) {
+ const { t } = useTranslation();
+ const canvas = useRef<HTMLCanvasElement>(null);
+ const preview = useRef<HTMLDivElement>(null);
+ const panel = useRef<HTMLElement>(null);
+ const sourceCanvas = useRef<HTMLCanvasElement | null>(null);
+ const paintedRange = useRef({ start: -1, end: -1 });
+ const scrollPaint = useRef(0);
+ const growthFrame = useRef(0);
+ const followGrowth = useRef(true);
+ const previousHeight = useRef(begin.first.height);
+ const reducedMotion = useReducedMotion();
+ const followEdge = useRef<'start' | 'end'>('start');
+ const runtime = useRef({ active: true, finishing: false, capture: new ScrollCapture(begin.first), pending: null as Promise<void> | null, automatic: false, stillFrames: 0, unmatchedSince: 0, movingUntil: 0 });
+ const [height, setHeight] = useState(begin.first.height);
+ const [automatic, setAutomatic] = useState(false);
+ const [busy, setBusy] = useState(false);
+ const [status, setStatus] = useState('scrollHint');
+ const [error, setError] = useState('');
+ const layout = begin.scrollLayout!;
+ const ratio = layout.preview.width / begin.first.width;
+ const previewHeight = Math.min(layout.preview.height, Math.ceil(height * ratio));
+ const initialPreviewHeight = Math.min(layout.preview.height, Math.ceil(begin.first.height * ratio));
+
+ function paintRange(destination = preview.current?.scrollTop ?? 0, force = false) {
+ const target = canvas.current;
+ const view = preview.current;
+ if (!target || !view) return;
+ const capture = runtime.current.capture;
+ const visibleRows = Math.ceil(layout.preview.height / ratio);
+ const current = Math.floor(view.scrollTop / ratio);
+ const next = Math.floor(destination / ratio);
+ const previous = paintedRange.current;
+ if (!force && current >= previous.start && Math.min(capture.height, current + visibleRows) <= previous.end) return;
+ // Buffer the current and destination viewports so native smooth scrolling
+ // moves existing pixels. Never allocate/convert the entire growing image.
+ const start = Math.max(0, Math.min(current, next) - Math.ceil(visibleRows / 2));
+ const end = Math.min(capture.height, Math.max(current, next) + visibleRows * 2);
+ const image = capture.image(start, end - start);
+ const source = sourceCanvas.current ??= document.createElement('canvas');
+ source.width = image.width; source.height = image.height;
+ source.getContext('2d')!.putImageData(bitmapToImageData(image), 0, 0);
+ const density = Math.min(2, window.devicePixelRatio || 1);
+ target.width = Math.max(1, Math.round(image.width * ratio * density));
+ target.height = Math.max(1, Math.round(image.height * ratio * density));
+ target.style.top = `${start * ratio}px`;
+ target.style.height = `${image.height * ratio}px`;
+ target.getContext('2d')!.drawImage(source, 0, 0, target.width, target.height);
+ paintedRange.current = { start, end };
+ }
+
+ useLayoutEffect(() => {
+ const view = preview.current;
+ const container = panel.current;
+ if (!view || !container) return;
+ cancelAnimationFrame(growthFrame.current);
+ followGrowth.current = true;
+ const fromHeight = container.getBoundingClientRect().height;
+ // Prepending rebases every existing pixel. Compensate before painting so
+ // the old content stays still while the new strip is revealed above it.
+ const prepend = followEdge.current === 'start' ? (height - previousHeight.current) * ratio : 0;
+ previousHeight.current = height;
+ view.scrollTop += prepend;
+ const fromScroll = view.scrollTop;
+ const destination = followEdge.current === 'end' ? Math.max(0, height * ratio - previewHeight) : 0;
+ paintRange(destination, true);
+ const token = getComputedStyle(container).getPropertyValue('--motion-base').trim();
+ const duration = reducedMotion ? 0 : (parseFloat(token) || 0) * (token.endsWith('ms') ? 1 : 1000);
+ const started = performance.now();
+ // One linear timeline for growing height and following the captured edge.
+ // New samples retarget from the currently displayed geometry, not the old
+ // destination; independent CSS-height and native-scroll animations drift.
+ const advance = (now: number) => {
+ const progress = duration > 0 ? Math.min(1, (now - started) / duration) : 1;
+ container.style.height = `${fromHeight + (previewHeight - fromHeight) * progress}px`;
+ if (followGrowth.current) view.scrollTop = fromScroll + (destination - fromScroll) * progress;
+ if (progress < 1) growthFrame.current = requestAnimationFrame(advance);
+ };
+ advance(started);
+ return () => cancelAnimationFrame(growthFrame.current);
+ // The capture layout is fixed for this session; only accepted pixels animate.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [height, reducedMotion]);
+
+ async function changeAutomatic(enabled: boolean) {
+ const state = runtime.current;
+ if (state.finishing) return;
+ const accepted = await bridge.autoScroll(token, enabled);
+ if (!state.active || state.finishing) return;
+ state.automatic = accepted === true && enabled;
+ state.stillFrames = 0;
+ setAutomatic(state.automatic);
+ setError(accepted === 'accessibility' ? 'autoPermission' : accepted ? '' : 'autoUnavailable');
+ }
+
+ async function sample() {
+ const state = runtime.current;
+ const frame = await bridge.liveFrame(token, false, panel.current?.clientHeight);
+ if (!frame || !state.active || state.finishing) return;
+ if (state.automatic && frame.autoScrolling === false) {
+ state.automatic = false; setAutomatic(false); setError('autoUnavailable');
+ }
+ const match = state.capture.add(frame.image);
+ if (match === 'append' || match === 'prepend') {
+ followEdge.current = match === 'append' ? 'end' : 'start';
+ setHeight(state.capture.height);
+ state.movingUntil = performance.now() + 400;
+ state.stillFrames = 0; state.unmatchedSince = 0; setStatus('scrollHint'); setError('');
+ } else if (match === 'unmatched') {
+ state.unmatchedSince ||= performance.now();
+ if (performance.now() - state.unmatchedSince > 1500) {
+ if (state.capture.height > begin.first.height) setStatus('overlap');
+ if (state.automatic) await changeAutomatic(false);
+ }
+ } else {
+ state.unmatchedSince = 0;
+ setStatus(match === 'limit' ? 'limit' : 'scrollHint');
+ if (state.automatic && (match === 'limit' || ++state.stillFrames >= 8)) await changeAutomatic(false);
+ }
+ }
+
+ async function finish(action: 'edit' | 'copy' | 'save') {
+ const state = runtime.current;
+ if (state.finishing) return;
+ state.finishing = true; setBusy(true);
+ state.automatic = false; setAutomatic(false);
+ try {
+ await bridge.holdCapture(token);
+ await state.pending;
+ if (!state.active) return;
+ const bitmap = state.capture.image();
+ if (action === 'edit') await onEdit(bitmap);
+ else if (!await bridge.exportImage(token, { action, selection: begin.selection, image: bitmap })) throw new Error('Export rejected');
+ } catch {
+ if (state.active) { state.finishing = false; setBusy(false); setError('exportFailed'); }
+ }
+ }
+
+ useEffect(() => {
+ const state = runtime.current;
+ state.active = true;
+ let timer: ReturnType<typeof setTimeout>;
+ const tick = async () => {
+ if (!state.active) return;
+ if (state.finishing) { timer = setTimeout(tick, 200); return; }
+ const started = performance.now();
+ state.pending = sample().catch(() => { if (state.active && !state.finishing) { setError('captureFailed'); void changeAutomatic(false); } });
+ await state.pending;
+ state.pending = null;
+ // Track active manual scrolling more closely; idle and automatic scrolling
+ // keep their existing cadence (and automatic scrolling speed).
+ const interval = !state.automatic && performance.now() < state.movingUntil ? 100 : 200;
+ if (state.active) timer = setTimeout(tick, Math.max(0, interval - (performance.now() - started)));
+ };
+ timer = setTimeout(tick, 200);
+ const key = (event: KeyboardEvent) => {
+ if (event.key === 'Escape') { event.preventDefault(); bridge.cancel(token); }
+ else if (event.key === 'Enter' || ((event.ctrlKey || event.metaKey) && ['c', 's'].includes(event.key.toLowerCase()))) {
+ event.preventDefault(); void finish(event.key.toLowerCase() === 's' ? 'save' : 'copy');
+ }
+ };
+ window.addEventListener('keydown', key);
+ return () => { state.active = false; clearTimeout(timer); cancelAnimationFrame(scrollPaint.current); window.removeEventListener('keydown', key); void bridge.holdCapture(token).catch(() => {}); };
+ // A fresh session mounts a fresh overlay; mutable capture state lives in runtime.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, []);
+
+ const actions = [
+ { key: 'edit', label: t('regionScreenshot.live.edit'), Icon: Pencil, run: () => void finish('edit') },
+ { key: 'save', label: t('regionScreenshot.save'), Icon: Download, run: () => void finish('save') },
+ { key: 'cancel', label: t('regionScreenshot.cancel'), Icon: X, run: () => bridge.cancel(token) },
+ { key: 'copy', label: t('regionScreenshot.live.finish'), Icon: Check, run: () => void finish('copy') },
+ ];
+ const message = error === 'captureFailed' ? t('regionScreenshot.captureFailed') : t(`regionScreenshot.live.${error || status}`);
+ return <div className="fixed inset-0 pointer-events-none select-none text-[var(--text-primary)]">
+ <div aria-hidden className="absolute border border-[var(--text-primary)]" style={{ left: begin.selection.x - 1, top: begin.selection.y - 1, width: begin.selection.width + 2, height: begin.selection.height + 2, boxShadow: '0 0 0 1px var(--surface-elevated)' }} />
+ <aside ref={panel} aria-label={t('regionScreenshot.live.preview')} className="absolute overflow-hidden pointer-events-auto" style={{ left: layout.preview.x, bottom: layout.viewport.height - layout.preview.y - layout.preview.height, width: layout.preview.width, height: initialPreviewHeight }}>
+ <div ref={preview} tabIndex={0} className="h-full w-full overflow-y-auto overflow-x-hidden [&::-webkit-scrollbar]:hidden" style={{ scrollbarWidth: 'none', overflowAnchor: 'none', scrollBehavior: 'auto' }} onWheel={() => { followGrowth.current = false; }} onScroll={() => {
+ cancelAnimationFrame(scrollPaint.current);
+ scrollPaint.current = requestAnimationFrame(() => paintRange());
+ }}>
+ <div className="relative w-full" style={{ height: Math.ceil(height * ratio) }}><canvas ref={canvas} className="absolute left-0 block w-full" /></div>
+ </div>
+ <p role="status" className="sr-only">{message}</p>
+ <span className="sr-only">{begin.first.width} × {height}</span>
+ {(error || status !== 'scrollHint') && <p role="alert" className="absolute inset-x-0 top-0 bg-[var(--surface-elevated)] px-2 py-1 text-11 text-[var(--text-secondary)] pointer-events-none">{message}</p>}
+ </aside>
+ <div className="absolute flex items-center justify-center gap-1 rounded-lg border border-[var(--border-default)] bg-[var(--surface-elevated)] pointer-events-auto" style={{ left: layout.actions.x, top: layout.actions.y, width: layout.actions.width, height: layout.actions.height }}>
+ {actions.map(({ key, label, Icon, run }) => <Tip key={key} text={label} side="top"><Button size="xs" variant={key === 'copy' ? 'cta' : 'secondary'} className="w-7 px-0" aria-label={label} disabled={busy} onClick={run}><Icon size={16} aria-hidden /></Button></Tip>)}
+ </div>
+ <div className="absolute flex items-center justify-center rounded-lg border border-[var(--border-default)] bg-[var(--surface-elevated)] pointer-events-auto" style={{ left: layout.auto.x, top: layout.auto.y, width: layout.auto.width, height: layout.auto.height }}>
+ <Tip text={t('regionScreenshot.live.scrollHint')} side="top"><Button size="sm" variant="secondary" disabled={busy} onClick={() => void changeAutomatic(!automatic)}>{t(`regionScreenshot.live.${automatic ? 'stopScroll' : 'autoScroll'}`)}</Button></Tip>
+ </div>
+ </div>;
+}
diff --git a/apps/desktop/src/renderer/features/region-screenshot/__tests__/screenshotRendering.test.tsx b/apps/desktop/src/renderer/features/region-screenshot/__tests__/screenshotRendering.test.tsx
new file mode 100644
index 0000000000..b226a439d5
--- /dev/null
+++ b/apps/desktop/src/renderer/features/region-screenshot/__tests__/screenshotRendering.test.tsx
@@ -0,0 +1,70 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { ScreenshotErrorBoundary } from '../ScreenshotErrorBoundary';
+import { Magnifier } from '../Magnifier';
+import { bitmapToImageData, imageDataToBitmap } from '../bridge';
+
+vi.mock('@/lib/logger', () => ({ createLogger: () => ({ warn: vi.fn() }) }));
+vi.mock('react-i18next', () => ({ useTranslation: () => ({ t: (key: string) => key }) }));
+
+// 测试价值:生产 React 边界出错会释放浮层,放大镜坐标与屏幕像素一致。
+// 纯几何测试没有组件/错误路径;最小输入为 render throw、2x 屏配 3x 定格图。
+// tier: unit;仅此文件需要 DOM,和主进程窗口模拟分开。
+describe('screenshot rendering recovery', () => {
+ afterEach(() => {
+ cleanup();
+ vi.restoreAllMocks();
+ vi.unstubAllGlobals();
+ });
+ // Unit: packed-pixel conversion must preserve alpha, immutable input and byte
+ // views from IPC. Existing geometry/rendering tests do not inspect these bytes.
+ it.each([0, 1])('round-trips screenshot pixels with byte offset %s', (offset) => {
+ vi.stubGlobal('ImageData', class {
+ data: Uint8ClampedArray;
+ constructor(readonly width: number, readonly height: number) {
+ this.data = new Uint8ClampedArray(width * height * 4);
+ }
+ });
+ const bytes = [9, 17, 33, 127, 100, 201, 255, 0];
+ const data = new Uint8Array(new ArrayBuffer(bytes.length + offset), offset);
+ data.set(bytes);
+ const bitmap = { width: 2, height: 1, data };
+ const image = bitmapToImageData(bitmap);
+ expect(Array.from(image.data)).toEqual([33, 17, 9, 127, 255, 201, 100, 0]);
+ expect(bitmapToImageData(bitmap, image)).toBe(image);
+ expect(Array.from(data)).toEqual(bytes);
+ expect(Array.from(imageDataToBitmap(image).data)).toEqual(bytes);
+ expect(bitmapToImageData({ width: 1, height: 2, data }, image)).not.toBe(image);
+ });
+ it('releases the screen when a child crashes instead of showing the application crash page', () => {
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+ const fail = vi.fn();
+ function Broken(): never {
+ throw new Error('broken overlay');
+ }
+ const { container } = render(
+ <ScreenshotErrorBoundary onFailure={fail}>
+ <Broken />
+ </ScreenshotErrorBoundary>,
+ );
+ expect(fail).toHaveBeenCalledTimes(1);
+ expect(container.childElementCount).toBe(0);
+ });
+ it.each([1.25, 2])(
+ 'shows physical screen coordinates at %sx independently of capture resolution',
+ (scaleFactor) => {
+ render(
+ <Magnifier
+ frame={null}
+ frameSize={{ width: 300, height: 300 }}
+ viewport={{ width: 100, height: 100 }}
+ point={{ x: 20, y: 40 }}
+ color={null}
+ scaleFactor={scaleFactor}
+ />,
+ );
+ expect(screen.getByText(`${20 * scaleFactor}, ${40 * scaleFactor}`)).toBeTruthy();
+ },
+ );
+});
diff --git a/apps/desktop/src/renderer/features/region-screenshot/__tests__/screenshotTaskHandoff.test.ts b/apps/desktop/src/renderer/features/region-screenshot/__tests__/screenshotTaskHandoff.test.ts
new file mode 100644
index 0000000000..6f18910884
--- /dev/null
+++ b/apps/desktop/src/renderer/features/region-screenshot/__tests__/screenshotTaskHandoff.test.ts
@@ -0,0 +1,123 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { ComposerDraft } from '@/lib/composerDraftStore';
+import type { RegionScreenshotComposeRequest } from '../../../../shared/regionScreenshot';
+
+vi.mock('@/i18n', () => ({ default: { t: (key: string) => key } }));
+import { getDraft, saveDraft, clearDraft, discardDraft, setComposerDraftOwner } from '@/lib/composerDraftStore';
+import { setDataOwnerGeneration } from '@/contexts/dataOwnerGeneration';
+const drafts = {
+ get current() { return getDraft(NEW_MAKER_DRAFT_KEY); },
+ set current(value: ComposerDraft | undefined) {
+ if (value) saveDraft(NEW_MAKER_DRAFT_KEY, value);
+ else clearDraft(NEW_MAKER_DRAFT_KEY);
+ },
+};
+import { applyScreenshotComposeRequest } from '../screenshotTaskHandoff';
+import { NEW_MAKER_DRAFT_KEY } from '@/features/cc-agent/newMakerDraftKeys';
+import { takeComposerSubmitRequest } from '@/lib/composerActionsBus';
+
+const original: ComposerDraft = {
+ text: {
+ type: 'doc',
+ content: [{ type: 'paragraph', content: [{ type: 'text', text: 'my original draft' }] }],
+ },
+ attachments: [],
+};
+const request = (id: string, action = 'translate'): RegionScreenshotComposeRequest => ({
+ id,
+ ownerStamp: { dataOwnerId: 'owner-a', ownerGeneration: 1 },
+ action: action as RegionScreenshotComposeRequest['action'],
+ url: `image:${id}`,
+ filename: `${id}.png`,
+ bytes: 16,
+ width: 2,
+ height: 2,
+});
+
+// 测试价值:生产 applyScreenshotComposeRequest 保护连续 AI 操作和恢复期间的新输入。
+// 既有 bus 测试只验证一次性消费,不验证草稿;最小失败输入为两次动作、清空、推进 500ms。
+// tier: unit,使用真实进程内草稿存储;不启动编辑器或真实发送。
+describe('screenshot draft restoration', () => {
+ beforeEach(() => {
+ vi.stubGlobal('window', { electronAPI: { cindyMediaStorage: { reportDraftUrls: vi.fn() } } });
+ setDataOwnerGeneration('owner-a', 1);
+ setComposerDraftOwner('owner-a');
+ vi.useFakeTimers();
+ });
+ afterEach(async () => {
+ await vi.runAllTimersAsync();
+ takeComposerSubmitRequest(NEW_MAKER_DRAFT_KEY);
+ vi.useRealTimers();
+ drafts.current = undefined;
+ setComposerDraftOwner('owner-a');
+ clearDraft(NEW_MAKER_DRAFT_KEY);
+ vi.unstubAllGlobals();
+ });
+ it('retains the original draft across consecutive quick actions', async () => {
+ vi.useFakeTimers();
+ drafts.current = original;
+ applyScreenshotComposeRequest(request('a'), vi.fn());
+ applyScreenshotComposeRequest(request('b'), vi.fn());
+ await vi.advanceTimersByTimeAsync(500);
+ drafts.current = undefined;
+ await vi.advanceTimersByTimeAsync(500);
+ expect(JSON.stringify(drafts.current)).toContain('my original draft');
+ });
+ it('merges the original with text entered after a successful send', async () => {
+ vi.useFakeTimers();
+ drafts.current = original;
+ applyScreenshotComposeRequest(request('c'), vi.fn());
+ drafts.current = {
+ text: {
+ type: 'doc',
+ content: [{ type: 'paragraph', content: [{ type: 'text', text: 'new typing' }] }],
+ },
+ attachments: [],
+ };
+ await vi.advanceTimersByTimeAsync(500);
+ expect(JSON.stringify(drafts.current)).toContain('my original draft');
+ expect(JSON.stringify(drafts.current)).toContain('new typing');
+ });
+ it('preserves ask attachments alongside an outstanding automatic action', async () => {
+ vi.useFakeTimers();
+ drafts.current = original;
+ applyScreenshotComposeRequest(request('d'), vi.fn());
+ applyScreenshotComposeRequest(request('e', 'ask'), vi.fn());
+ await vi.advanceTimersByTimeAsync(30_000);
+ expect(JSON.stringify(drafts.current)).toContain('my original draft');
+ expect(drafts.current?.attachments.map((file) => file.url)).toEqual(['image:d', 'image:e']);
+ expect(takeComposerSubmitRequest(NEW_MAKER_DRAFT_KEY)).toBeNull();
+ });
+ // Unit: same-owner generation bumps retain drafts; account switches restore only
+ // the captured namespace. Real draft storage also protects explicitly discarded input.
+ it.each(['generation', 'account', 'discard'] as const)('preserves recovery boundaries after %s', async (change) => {
+ drafts.current = original;
+ applyScreenshotComposeRequest(request('recovery'), vi.fn());
+ if (change === 'account') {
+ setDataOwnerGeneration('owner-b', 2);
+ setComposerDraftOwner('owner-b');
+ drafts.current = { text: null, attachments: [] };
+ } else if (change === 'discard') discardDraft(NEW_MAKER_DRAFT_KEY);
+ else {
+ setDataOwnerGeneration('owner-a', 2);
+ clearDraft(NEW_MAKER_DRAFT_KEY);
+ }
+ await vi.advanceTimersByTimeAsync(500);
+ if (change === 'account') {
+ expect(drafts.current).toEqual({ text: null, attachments: [] });
+ clearDraft(NEW_MAKER_DRAFT_KEY);
+ setComposerDraftOwner('owner-a');
+ }
+ if (change === 'discard') expect(drafts.current).toBeUndefined();
+ else expect(JSON.stringify(drafts.current)).toContain('my original draft');
+ });
+ it('drops a taken screenshot delivered after the renderer owner changes', () => {
+ drafts.current = original;
+ setDataOwnerGeneration('owner-b', 2);
+ const navigate = vi.fn();
+ applyScreenshotComposeRequest(request('stale'), navigate);
+ expect(drafts.current).toEqual(original);
+ expect(navigate).not.toHaveBeenCalled();
+ expect(takeComposerSubmitRequest(NEW_MAKER_DRAFT_KEY)).toBeNull();
+ });
+});
diff --git a/apps/desktop/src/renderer/features/region-screenshot/annotations.ts b/apps/desktop/src/renderer/features/region-screenshot/annotations.ts
new file mode 100644
index 0000000000..9328770689
--- /dev/null
+++ b/apps/desktop/src/renderer/features/region-screenshot/annotations.ts
@@ -0,0 +1,461 @@
+/**
+ * 截图标注: 数据模型、绘制与命中测试。
+ *
+ * 标注坐标一律是浮层 DIP (与选区同一坐标系), 屏幕显示与最终导出调用同一个
+ * {@link drawAnnotations}, 只是画布变换不同 —— 所见即所得。马赛克 / 模糊直接取
+ * 定格原图的像素, 不受先画的其它标注影响。
+ */
+
+import type { RegionPoint, RegionRect } from '../../../shared/regionScreenshot';
+import { SCREENSHOT_INK, type ScreenshotInk } from './screenshotColors';
+
+export type AnnotationTool =
+ | 'rect'
+ | 'ellipse'
+ | 'line'
+ | 'arrow'
+ | 'pen'
+ | 'marker'
+ | 'text'
+ | 'mosaic'
+ | 'blur'
+ | 'step';
+
+export const ANNOTATION_TOOLS: readonly AnnotationTool[] = [
+ 'rect',
+ 'ellipse',
+ 'line',
+ 'arrow',
+ 'pen',
+ 'marker',
+ 'text',
+ 'mosaic',
+ 'blur',
+ 'step',
+];
+
+/** 粗细 / 字号 / 强度三档。 */
+export type AnnotationSize = 0 | 1 | 2;
+
+/** 标注墨水 (取值见 screenshotColors); 标注里只存墨水名, 绘制时再取色。 */
+export const ANNOTATION_COLORS: readonly ScreenshotInk[] = [
+ 'red',
+ 'yellow',
+ 'green',
+ 'blue',
+ 'black',
+ 'white',
+];
+export const DEFAULT_ANNOTATION_COLOR: ScreenshotInk = 'red';
+export const DEFAULT_MARKER_COLOR: ScreenshotInk = 'yellow';
+
+const STROKE_WIDTH = [2, 4, 6];
+const MARKER_WIDTH = [12, 18, 26];
+export const TEXT_SIZE = [16, 22, 30];
+const STEP_RADIUS = [11, 14, 18];
+const MOSAIC_BLOCK = [6, 10, 16];
+const BLUR_RADIUS = [4, 8, 14];
+
+interface Base {
+ id: string;
+ color: ScreenshotInk;
+ size: AnnotationSize;
+}
+
+export type ShapeAnnotation = Base & {
+ kind: 'rect' | 'ellipse' | 'line' | 'arrow' | 'mosaic' | 'blur';
+ from: RegionPoint;
+ to: RegionPoint;
+};
+export type StrokeAnnotation = Base & { kind: 'pen' | 'marker'; points: RegionPoint[] };
+export type TextAnnotation = Base & { kind: 'text'; at: RegionPoint; text: string };
+export type StepAnnotation = Base & { kind: 'step'; at: RegionPoint; number: number };
+export type Annotation = ShapeAnnotation | StrokeAnnotation | TextAnnotation | StepAnnotation;
+
+/** 马赛克 / 模糊的取样来源: 定格原图及其相对 DIP 的缩放。 */
+export interface AnnotationSource {
+ frame: CanvasImageSource;
+ /** 原图像素 / DIP。 */
+ ratioX: number;
+ ratioY: number;
+ /** Optional placement of a completed long screenshot inside the same editor. */
+ offsetX?: number;
+ offsetY?: number;
+}
+
+export function textFont(size: AnnotationSize): string {
+ return `500 ${TEXT_SIZE[size]}px Inter, "HarmonyOS Sans SC", system-ui, sans-serif`;
+}
+
+export const TEXT_LINE_HEIGHT = 1.25;
+
+export function shapeRect(from: RegionPoint, to: RegionPoint): RegionRect {
+ return {
+ x: Math.min(from.x, to.x),
+ y: Math.min(from.y, to.y),
+ width: Math.abs(to.x - from.x),
+ height: Math.abs(to.y - from.y),
+ };
+}
+
+/** 序号圈上的数字在浅色墨水上用黑字, 其余用白字。 */
+function stepTextColor(color: ScreenshotInk): string {
+ return color === 'white' || color === 'yellow' ? SCREENSHOT_INK.black : SCREENSHOT_INK.white;
+}
+
+let scratch: HTMLCanvasElement | null = null;
+function scratchCanvas(width: number, height: number): CanvasRenderingContext2D | null {
+ scratch ??= document.createElement('canvas');
+ scratch.width = Math.max(1, Math.ceil(width));
+ scratch.height = Math.max(1, Math.ceil(height));
+ return scratch.getContext('2d');
+}
+
+function drawMosaic(
+ ctx: CanvasRenderingContext2D,
+ rect: RegionRect,
+ size: AnnotationSize,
+ source: AnnotationSource,
+): void {
+ const block = MOSAIC_BLOCK[size];
+ const cols = Math.max(1, Math.round(rect.width / block));
+ const rows = Math.max(1, Math.round(rect.height / block));
+ const tiny = scratchCanvas(cols, rows);
+ if (!tiny) return;
+ tiny.imageSmoothingEnabled = true;
+ tiny.imageSmoothingQuality = 'high';
+ tiny.drawImage(
+ source.frame,
+ (rect.x - (source.offsetX ?? 0)) * source.ratioX,
+ (rect.y - (source.offsetY ?? 0)) * source.ratioY,
+ rect.width * source.ratioX,
+ rect.height * source.ratioY,
+ 0,
+ 0,
+ cols,
+ rows,
+ );
+ ctx.save();
+ ctx.imageSmoothingEnabled = false;
+ ctx.drawImage(tiny.canvas, 0, 0, cols, rows, rect.x, rect.y, rect.width, rect.height);
+ ctx.restore();
+}
+
+function drawBlur(
+ ctx: CanvasRenderingContext2D,
+ rect: RegionRect,
+ size: AnnotationSize,
+ source: AnnotationSource,
+): void {
+ // 模糊在原图像素上做, 四周多取一圈, 边缘才不会被透明像素拉淡。
+ const radius = BLUR_RADIUS[size];
+ const margin = radius * 2;
+ const sx = (rect.x - margin - (source.offsetX ?? 0)) * source.ratioX;
+ const sy = (rect.y - margin - (source.offsetY ?? 0)) * source.ratioY;
+ const sw = (rect.width + margin * 2) * source.ratioX;
+ const sh = (rect.height + margin * 2) * source.ratioY;
+ const blurred = scratchCanvas(sw, sh);
+ if (!blurred) return;
+ blurred.filter = `blur(${radius * source.ratioX}px)`;
+ blurred.drawImage(source.frame, sx, sy, sw, sh, 0, 0, sw, sh);
+ blurred.filter = 'none';
+ ctx.save();
+ ctx.beginPath();
+ ctx.rect(rect.x, rect.y, rect.width, rect.height);
+ ctx.clip();
+ ctx.drawImage(
+ blurred.canvas,
+ 0,
+ 0,
+ sw,
+ sh,
+ rect.x - margin,
+ rect.y - margin,
+ rect.width + margin * 2,
+ rect.height + margin * 2,
+ );
+ ctx.restore();
+}
+
+function drawArrow(
+ ctx: CanvasRenderingContext2D,
+ from: RegionPoint,
+ to: RegionPoint,
+ width: number,
+): void {
+ const angle = Math.atan2(to.y - from.y, to.x - from.x);
+ const length = Math.hypot(to.x - from.x, to.y - from.y);
+ const head = Math.min(length, width * 3 + 10);
+ const spread = Math.PI / 7;
+ const base = { x: to.x - Math.cos(angle) * head * 0.8, y: to.y - Math.sin(angle) * head * 0.8 };
+ ctx.beginPath();
+ ctx.moveTo(from.x, from.y);
+ ctx.lineTo(base.x, base.y);
+ ctx.stroke();
+ ctx.beginPath();
+ ctx.moveTo(to.x, to.y);
+ ctx.lineTo(to.x - Math.cos(angle - spread) * head, to.y - Math.sin(angle - spread) * head);
+ ctx.lineTo(to.x - Math.cos(angle + spread) * head, to.y - Math.sin(angle + spread) * head);
+ ctx.closePath();
+ ctx.fill();
+}
+
+function drawStroke(ctx: CanvasRenderingContext2D, points: readonly RegionPoint[]): void {
+ if (points.length === 0) return;
+ ctx.beginPath();
+ ctx.moveTo(points[0].x, points[0].y);
+ if (points.length === 1) ctx.lineTo(points[0].x + 0.01, points[0].y);
+ for (let i = 1; i < points.length - 1; i++) {
+ const mid = { x: (points[i].x + points[i + 1].x) / 2, y: (points[i].y + points[i + 1].y) / 2 };
+ ctx.quadraticCurveTo(points[i].x, points[i].y, mid.x, mid.y);
+ }
+ if (points.length > 1) {
+ const last = points[points.length - 1];
+ ctx.lineTo(last.x, last.y);
+ }
+ ctx.stroke();
+}
+
+export function drawAnnotation(
+ ctx: CanvasRenderingContext2D,
+ annotation: Annotation,
+ source: AnnotationSource,
+): void {
+ ctx.save();
+ ctx.strokeStyle = SCREENSHOT_INK[annotation.color];
+ ctx.fillStyle = SCREENSHOT_INK[annotation.color];
+ ctx.lineCap = 'round';
+ ctx.lineJoin = 'round';
+ const width = STROKE_WIDTH[annotation.size];
+ ctx.lineWidth = width;
+ switch (annotation.kind) {
+ case 'rect': {
+ const r = shapeRect(annotation.from, annotation.to);
+ ctx.strokeRect(r.x, r.y, r.width, r.height);
+ break;
+ }
+ case 'ellipse': {
+ const r = shapeRect(annotation.from, annotation.to);
+ ctx.beginPath();
+ ctx.ellipse(r.x + r.width / 2, r.y + r.height / 2, r.width / 2, r.height / 2, 0, 0, Math.PI * 2);
+ ctx.stroke();
+ break;
+ }
+ case 'line':
+ ctx.beginPath();
+ ctx.moveTo(annotation.from.x, annotation.from.y);
+ ctx.lineTo(annotation.to.x, annotation.to.y);
+ ctx.stroke();
+ break;
+ case 'arrow':
+ drawArrow(ctx, annotation.from, annotation.to, width);
+ break;
+ case 'pen':
+ drawStroke(ctx, annotation.points);
+ break;
+ case 'marker':
+ // 荧光笔: 半透明宽笔, 叠在文字上仍能看清底下的内容。
+ ctx.globalAlpha = 0.4;
+ ctx.lineCap = 'square';
+ ctx.lineWidth = MARKER_WIDTH[annotation.size];
+ drawStroke(ctx, annotation.points);
+ break;
+ case 'mosaic': {
+ const r = shapeRect(annotation.from, annotation.to);
+ if (r.width >= 1 && r.height >= 1) drawMosaic(ctx, r, annotation.size, source);
+ break;
+ }
+ case 'blur': {
+ const r = shapeRect(annotation.from, annotation.to);
+ if (r.width >= 1 && r.height >= 1) drawBlur(ctx, r, annotation.size, source);
+ break;
+ }
+ case 'text': {
+ ctx.font = textFont(annotation.size);
+ ctx.textBaseline = 'top';
+ const lineHeight = TEXT_SIZE[annotation.size] * TEXT_LINE_HEIGHT;
+ annotation.text.split('\n').forEach((line, index) => {
+ ctx.fillText(line, annotation.at.x, annotation.at.y + index * lineHeight);
+ });
+ break;
+ }
+ case 'step': {
+ const radius = STEP_RADIUS[annotation.size];
+ ctx.beginPath();
+ ctx.arc(annotation.at.x, annotation.at.y, radius, 0, Math.PI * 2);
+ ctx.fill();
+ ctx.fillStyle = stepTextColor(annotation.color);
+ ctx.font = `600 ${Math.round(radius * 1.15)}px Inter, system-ui, sans-serif`;
+ ctx.textAlign = 'center';
+ ctx.textBaseline = 'middle';
+ ctx.fillText(String(annotation.number), annotation.at.x, annotation.at.y + radius * 0.05);
+ break;
+ }
+ }
+ ctx.restore();
+}
+
+export function drawAnnotations(
+ ctx: CanvasRenderingContext2D,
+ annotations: readonly Annotation[],
+ source: AnnotationSource,
+): void {
+ for (const annotation of annotations) drawAnnotation(ctx, annotation, source);
+}
+
+let measureContext: CanvasRenderingContext2D | null = null;
+
+/** 文字标注的外框 (DIP)。 */
+export function textBounds(annotation: TextAnnotation): RegionRect {
+ measureContext ??= document.createElement('canvas').getContext('2d');
+ const lines = annotation.text.split('\n');
+ const lineHeight = TEXT_SIZE[annotation.size] * TEXT_LINE_HEIGHT;
+ let width = 0;
+ if (measureContext) {
+ measureContext.font = textFont(annotation.size);
+ for (const line of lines) width = Math.max(width, measureContext.measureText(line).width);
+ }
+ return { x: annotation.at.x, y: annotation.at.y, width, height: lines.length * lineHeight };
+}
+
+/** 标注外框 (DIP), 用于选中框。 */
+export function annotationBounds(annotation: Annotation): RegionRect {
+ switch (annotation.kind) {
+ case 'text':
+ return textBounds(annotation);
+ case 'step': {
+ const r = STEP_RADIUS[annotation.size];
+ return { x: annotation.at.x - r, y: annotation.at.y - r, width: r * 2, height: r * 2 };
+ }
+ case 'pen':
+ case 'marker': {
+ const xs = annotation.points.map((p) => p.x);
+ const ys = annotation.points.map((p) => p.y);
+ const pad = (annotation.kind === 'marker' ? MARKER_WIDTH : STROKE_WIDTH)[annotation.size] / 2;
+ const x = Math.min(...xs) - pad;
+ const y = Math.min(...ys) - pad;
+ return { x, y, width: Math.max(...xs) + pad - x, height: Math.max(...ys) + pad - y };
+ }
+ default:
+ return shapeRect(annotation.from, annotation.to);
+ }
+}
+
+function distanceToSegment(p: RegionPoint, a: RegionPoint, b: RegionPoint): number {
+ const dx = b.x - a.x;
+ const dy = b.y - a.y;
+ const lengthSq = dx * dx + dy * dy;
+ const t = lengthSq === 0 ? 0 : Math.max(0, Math.min(1, ((p.x - a.x) * dx + (p.y - a.y) * dy) / lengthSq));
+ return Math.hypot(p.x - (a.x + t * dx), p.y - (a.y + t * dy));
+}
+
+const inside = (r: RegionRect, p: RegionPoint, pad = 0) =>
+ p.x >= r.x - pad && p.x <= r.x + r.width + pad && p.y >= r.y - pad && p.y <= r.y + r.height + pad;
+
+/**
+ * 指针是否点中标注。矩形 / 椭圆只认轮廓 (框内还能继续画新标注), 马赛克、模糊、
+ * 文字、序号认整个区域, 线条认笔迹附近。
+ */
+export function hitAnnotation(annotation: Annotation, point: RegionPoint): boolean {
+ const tolerance = 6;
+ switch (annotation.kind) {
+ case 'rect': {
+ const r = shapeRect(annotation.from, annotation.to);
+ return inside(r, point, tolerance) && !inside(
+ { x: r.x + tolerance, y: r.y + tolerance, width: r.width - tolerance * 2, height: r.height - tolerance * 2 },
+ point,
+ );
+ }
+ case 'ellipse': {
+ const r = shapeRect(annotation.from, annotation.to);
+ const rx = r.width / 2;
+ const ry = r.height / 2;
+ if (rx < 1 || ry < 1) return inside(r, point, tolerance);
+ const nx = (point.x - (r.x + rx)) / rx;
+ const ny = (point.y - (r.y + ry)) / ry;
+ const distance = Math.abs(Math.hypot(nx, ny) - 1) * Math.min(rx, ry);
+ return distance <= tolerance;
+ }
+ case 'line':
+ case 'arrow':
+ return distanceToSegment(point, annotation.from, annotation.to) <= tolerance + STROKE_WIDTH[annotation.size];
+ case 'pen':
+ case 'marker': {
+ const width = (annotation.kind === 'marker' ? MARKER_WIDTH : STROKE_WIDTH)[annotation.size];
+ const pts = annotation.points;
+ if (pts.length === 1) return Math.hypot(point.x - pts[0].x, point.y - pts[0].y) <= tolerance + width;
+ for (let i = 1; i < pts.length; i++) {
+ if (distanceToSegment(point, pts[i - 1], pts[i]) <= tolerance + width / 2) return true;
+ }
+ return false;
+ }
+ default:
+ return inside(annotationBounds(annotation), point, 2);
+ }
+}
+
+/** 最上层被点中的标注。 */
+export function annotationAt(
+ annotations: readonly Annotation[],
+ point: RegionPoint,
+): Annotation | null {
+ for (let i = annotations.length - 1; i >= 0; i--) {
+ if (hitAnnotation(annotations[i], point)) return annotations[i];
+ }
+ return null;
+}
+
+const shift = (p: RegionPoint, dx: number, dy: number) => ({ x: p.x + dx, y: p.y + dy });
+
+export function moveAnnotation(annotation: Annotation, dx: number, dy: number): Annotation {
+ switch (annotation.kind) {
+ case 'pen':
+ case 'marker':
+ return { ...annotation, points: annotation.points.map((p) => shift(p, dx, dy)) };
+ case 'text':
+ case 'step':
+ return { ...annotation, at: shift(annotation.at, dx, dy) };
+ default:
+ return { ...annotation, from: shift(annotation.from, dx, dy), to: shift(annotation.to, dx, dy) };
+ }
+}
+
+/** 画到一半就松手的标注 (点一下、几乎没拖) 不保留。 */
+export function isMeaningfulAnnotation(annotation: Annotation): boolean {
+ switch (annotation.kind) {
+ case 'pen':
+ case 'marker':
+ return annotation.points.length > 0;
+ case 'text':
+ return annotation.text.trim().length > 0;
+ case 'step':
+ return true;
+ default:
+ return Math.hypot(annotation.to.x - annotation.from.x, annotation.to.y - annotation.from.y) >= 3;
+ }
+}
+
+/** 按住 Shift: 直线 / 箭头吸附到 45° 的倍数, 矩形 / 椭圆取正方形 / 正圆。 */
+export function constrainShape(
+ kind: ShapeAnnotation['kind'],
+ from: RegionPoint,
+ to: RegionPoint,
+): RegionPoint {
+ const dx = to.x - from.x;
+ const dy = to.y - from.y;
+ if (kind === 'line' || kind === 'arrow') {
+ const angle = Math.round(Math.atan2(dy, dx) / (Math.PI / 4)) * (Math.PI / 4);
+ const length = Math.hypot(dx, dy);
+ return { x: from.x + Math.cos(angle) * length, y: from.y + Math.sin(angle) * length };
+ }
+ const side = Math.max(Math.abs(dx), Math.abs(dy));
+ return { x: from.x + Math.sign(dx || 1) * side, y: from.y + Math.sign(dy || 1) * side };
+}
+
+export function nextStepNumber(annotations: readonly Annotation[]): number {
+ let max = 0;
+ for (const annotation of annotations) {
+ if (annotation.kind === 'step') max = Math.max(max, annotation.number);
+ }
+ return max + 1;
+}
diff --git a/apps/desktop/src/renderer/features/region-screenshot/bridge.ts b/apps/desktop/src/renderer/features/region-screenshot/bridge.ts
new file mode 100644
index 0000000000..38b30b1d6d
--- /dev/null
+++ b/apps/desktop/src/renderer/features/region-screenshot/bridge.ts
@@ -0,0 +1,97 @@
+import type {
+ RegionRect,
+ RegionScreenshotBegin,
+ RegionScreenshotBitmap,
+ RegionScreenshotExport,
+ RegionScreenshotPinCommand,
+ RegionScreenshotPinInit,
+ RegionScreenshotPinState,
+} from '../../../shared/regionScreenshot';
+import type { RegionCaptureBegin, RegionCaptureFrame, RegionCaptureMode } from '../../../shared/regionCapture';
+
+/** 框选浮层 preload (regionScreenshotPreload) 暴露的能力。 */
+export interface RegionScreenshotOverlayBridge {
+ recordingControls(token: string, expanded: boolean, point?: { x: number; y: number }, dragging?: boolean): Promise<RegionRect | null>;
+ previewRecording(token: string, bytes: Uint8Array, format: 'webm' | 'gif'): Promise<boolean>;
+ /** `'accessibility'`: macOS 缺少辅助功能权限, 系统已弹出授权询问。 */
+ autoScroll(token: string, enabled: boolean): Promise<boolean | 'accessibility'>;
+ restoreEditor(token: string, image: RegionScreenshotBitmap): Promise<boolean>;
+ holdCapture(token: string): Promise<void>;
+ startLive(token: string, mode: RegionCaptureMode, selection: RegionRect): Promise<RegionCaptureBegin | null>;
+ liveFrame(token: string, keys: boolean, previewHeight?: number): Promise<RegionCaptureFrame | null>;
+ saveRecording(token: string, bytes: Uint8Array, format: 'webm' | 'gif'): Promise<boolean>;
+ shellReady(): void;
+ onBegin(callback: (payload: RegionScreenshotBegin) => void): () => void;
+ onEnd(callback: () => void): () => void;
+ onClear(callback: () => void): () => void;
+ painted(token: string): void;
+ focused(token: string): void;
+ selectionStarted(token: string): void;
+ copyText(token: string, text: string): void;
+ cancel(token: string): void;
+ abandon(): void;
+ elementsAt(token: string, windowId: number, x: number, y: number): Promise<RegionRect[]>;
+ exportImage(token: string, payload: RegionScreenshotExport): Promise<boolean>;
+}
+
+/** 贴图 preload (regionScreenshotPinPreload) 暴露的能力。 */
+export interface RegionScreenshotPinBridge {
+ shellReady(): void;
+ onInit(callback: (payload: RegionScreenshotPinInit) => void): () => void;
+ onState(callback: (state: RegionScreenshotPinState) => void): () => void;
+ painted(): void;
+ dragStart(): void;
+ dragMove(): void;
+ zoom(steps: number, x: number, y: number): void;
+ opacity(steps: number): void;
+ menu(): void;
+ command(command: RegionScreenshotPinCommand): void;
+ unlockHover(hovering: boolean): void;
+}
+
+declare global {
+ interface Window {
+ regionScreenshot?: RegionScreenshotOverlayBridge;
+ regionScreenshotEditor?: Pick<RegionScreenshotOverlayBridge, 'shellReady' | 'onBegin' | 'onEnd' | 'painted' | 'cancel' | 'exportImage'> & { failed(): void; minimize(token: string): void };
+ regionScreenshotPin?: RegionScreenshotPinBridge;
+ }
+}
+
+const littleEndian = new Uint8Array(new Uint32Array([1]).buffer)[0] === 1;
+
+/** Swap whole pixels when aligned; keep byte views and in-place export supported. */
+function swapRedBlue(source: Uint8Array | Uint8ClampedArray, target: Uint8Array | Uint8ClampedArray): void {
+ if (littleEndian && source.byteOffset % 4 === 0 && target.byteOffset % 4 === 0) {
+ const input = new Uint32Array(source.buffer, source.byteOffset, source.length / 4);
+ const output = new Uint32Array(target.buffer, target.byteOffset, target.length / 4);
+ for (let i = 0; i < input.length; i++) {
+ const pixel = input[i];
+ output[i] = (pixel & 0xff00ff00) | ((pixel & 0xff) << 16) | ((pixel >>> 16) & 0xff);
+ }
+ return;
+ }
+ for (let i = 0; i < source.length; i += 4) {
+ const blue = source[i];
+ target[i] = source[i + 2];
+ target[i + 1] = source[i + 1];
+ target[i + 2] = blue;
+ target[i + 3] = source[i + 3];
+ }
+}
+
+/** BGRA → RGBA. A caller-owned destination may be reused; source stays immutable. */
+export function bitmapToImageData(bitmap: RegionScreenshotBitmap, reuse?: ImageData): ImageData {
+ const source = bitmap.data;
+ const image = reuse?.width === bitmap.width && reuse.height === bitmap.height
+ ? reuse
+ : new ImageData(bitmap.width, bitmap.height);
+ swapRedBlue(source, image.data);
+ return image;
+}
+
+/** 画布像素 (RGBA) → Electron 位图 (BGRA), 原地交换后复用同一块内存。 */
+export function imageDataToBitmap(image: ImageData): RegionScreenshotBitmap {
+ const data = new Uint8Array(image.data.buffer, image.data.byteOffset, image.data.byteLength);
+ swapRedBlue(data, data);
+ return { width: image.width, height: image.height, data: data as Uint8Array<ArrayBuffer> };
+}
diff --git a/apps/desktop/src/renderer/features/region-screenshot/captureRecorder.test.ts b/apps/desktop/src/renderer/features/region-screenshot/captureRecorder.test.ts
new file mode 100644
index 0000000000..1efcf3c40f
--- /dev/null
+++ b/apps/desktop/src/renderer/features/region-screenshot/captureRecorder.test.ts
@@ -0,0 +1,83 @@
+import { afterEach, expect, it, vi } from 'vitest';
+import { CaptureRecorder } from './captureRecorder';
+import { finalizeWebmDuration } from './webmDuration';
+
+// Real playback reported Infinity and could not show a timeline. Existing tests
+// only decoded pixels. Minimal streaming WebM Info without Duration; tier: unit.
+it('finalizes streaming WebM duration without changing its encoded frames', () => {
+ const stream = new Uint8Array([0x18, 0x53, 0x80, 0x67, 0xff, 0x15, 0x49, 0xa9, 0x66, 0x87, 0x2a, 0xd7, 0xb1, 0x83, 0x0f, 0x42, 0x40, 0x1f, 0x43, 0xb6, 0x75, 0x83, 1, 2, 3]);
+ const result = finalizeWebmDuration(stream, 1234);
+ expect(result[9]).toBe(0x92); // Info grows by the eleven-byte Duration element.
+ expect(new DataView(result.buffer).getFloat64(20)).toBe(1234);
+ expect(result.subarray(28)).toEqual(stream.subarray(17));
+ expect(finalizeWebmDuration(result, 999)).toBe(result);
+ expect(() => finalizeWebmDuration(stream.subarray(0, 12), 100)).toThrow('Invalid WebM metadata');
+});
+
+// Unit regression: the UI matrix produced an empty short WebM that was reported
+// as saved. Exercise the encoder's real finish boundary with an empty browser
+// stop event; geometry and browser playback tests do not cover this outcome.
+afterEach(() => vi.unstubAllGlobals());
+
+it('rejects a recording when the browser stops without encoded frames', async () => {
+ class EmptyRecorder {
+ static isTypeSupported() { return true; }
+ state = 'recording';
+ onstop: (() => void) | null = null;
+ start() {}
+ stop() { this.state = 'inactive'; queueMicrotask(() => this.onstop?.()); }
+ }
+ vi.stubGlobal('MediaRecorder', EmptyRecorder);
+ const track = { stop: vi.fn(), requestFrame: vi.fn() };
+ const canvas = { captureStream: () => ({ getTracks: () => [track], getVideoTracks: () => [track] }) } as unknown as HTMLCanvasElement;
+ const recorder = new CaptureRecorder(canvas, 'webm', () => {});
+ recorder.add(0);
+ await expect(recorder.finish(1)).rejects.toThrow('No video frames were encoded');
+ expect(track.stop).toHaveBeenCalled();
+});
+
+// Unit: consecutive identical GIF frames may coalesce, but their display time
+// and a one-pixel change must survive pause/resume. WebM tests miss this path.
+// Read standard GIF block metadata independently of the encoder's state.
+function frameDelays(bytes: Uint8Array): number[] {
+ let at = 13 + (bytes[10] & 128 ? 3 * 2 ** ((bytes[10] & 7) + 1) : 0);
+ const delays: number[] = [];
+ let delay = 0;
+ const skipBlocks = () => { while (bytes[at]) { at += bytes[at] + 1; } at++; };
+ while (bytes[at] !== 0x3b && at < bytes.length) {
+ const block = bytes[at++];
+ if (block === 0x21) {
+ const label = bytes[at++];
+ if (label === 0xf9) delay = (bytes[at + 2] | (bytes[at + 3] << 8)) * 10;
+ skipBlocks();
+ } else if (block === 0x2c) {
+ const packed = bytes[at + 8];
+ at += 9 + (packed & 128 ? 3 * 2 ** ((packed & 7) + 1) : 0);
+ at++; // LZW code size
+ skipBlocks();
+ delays.push(delay);
+ } else throw new Error(`Unexpected GIF block ${block}`);
+ }
+ expect(bytes[at]).toBe(0x3b);
+ return delays;
+}
+
+it('coalesces identical GIF frames without losing elapsed time or changes after resume', async () => {
+ const pixels = new Uint8ClampedArray([255, 0, 0, 255, 255, 0, 0, 255]);
+ const canvas = { width: 2, height: 1, getContext: () => ({
+ getImageData: () => ({ data: pixels.slice() }),
+ }) } as unknown as HTMLCanvasElement;
+ const recorder = new CaptureRecorder(canvas, 'gif', () => {});
+ recorder.add(0);
+ recorder.add(100);
+ recorder.add(200);
+ pixels.set([0, 0, 255, 255], 4);
+ recorder.add(300);
+ recorder.pause(400);
+ recorder.resume();
+ recorder.add(400);
+ recorder.add(500);
+ const bytes = await recorder.finish(600);
+ expect(frameDelays(bytes)).toEqual([300, 100, 200]);
+ recorder.dispose();
+});
diff --git a/apps/desktop/src/renderer/features/region-screenshot/captureRecorder.ts b/apps/desktop/src/renderer/features/region-screenshot/captureRecorder.ts
new file mode 100644
index 0000000000..6ce806b50a
--- /dev/null
+++ b/apps/desktop/src/renderer/features/region-screenshot/captureRecorder.ts
@@ -0,0 +1,107 @@
+import { GIFEncoder, applyPalette, quantize } from 'gifenc';
+import { MAX_RECORDING_BYTES } from '../../../shared/regionCapture';
+import { finalizeWebmDuration } from './webmDuration';
+
+/** Bounded, local-only encoding. Source pixels are supplied by the host's selected region. */
+export class CaptureRecorder {
+ private readonly gif;
+ private readonly recorder: MediaRecorder | null;
+ private readonly stream: MediaStream | null;
+ private readonly chunks: Blob[] = [];
+ private bytes = 0;
+ private previous: { pixels: Uint8ClampedArray; index: Uint8Array; palette: number[][]; at: number } | null = null;
+ private stopped = false;
+ private failure: Error | null = null;
+
+ constructor(private readonly canvas: HTMLCanvasElement, readonly format: 'webm' | 'gif', private readonly onLimit: () => void) {
+ this.gif = format === 'gif' ? GIFEncoder() : null;
+ this.stream = format === 'webm' ? canvas.captureStream(0) : null;
+ if (this.stream) {
+ const mimeType = ['video/webm;codecs=vp9', 'video/webm;codecs=vp8', 'video/webm'].find((type) => MediaRecorder.isTypeSupported(type));
+ if (!mimeType) { this.dispose(); throw new Error('WebM recording unavailable'); }
+ this.recorder = new MediaRecorder(this.stream, { mimeType, videoBitsPerSecond: 5_000_000 });
+ this.recorder.ondataavailable = ({ data }) => {
+ if (!data.size) return;
+ if (this.bytes + data.size > MAX_RECORDING_BYTES) {
+ this.failure = new Error('Recording size limit');
+ this.onLimit();
+ return;
+ }
+ this.chunks.push(data);
+ this.bytes += data.size;
+ if (this.bytes > MAX_RECORDING_BYTES - 4 * 1024 * 1024) this.onLimit();
+ };
+ this.recorder.onerror = () => { this.failure = new Error('Recording failed'); this.onLimit(); };
+ this.recorder.start(1000);
+ } else this.recorder = null;
+ }
+
+ add(at: number): void {
+ if (this.stopped) return;
+ if (this.recorder) {
+ (this.stream!.getVideoTracks()[0] as CanvasCaptureMediaStreamTrack).requestFrame();
+ } else if (this.gif) {
+ const pixels = this.canvas.getContext('2d', { willReadFrequently: true })!.getImageData(0, 0, this.canvas.width, this.canvas.height);
+ // Hold identical frames until the next change, pause or finish. Exact RGBA
+ // comparison preserves small cursor/text changes and the full hold duration.
+ if (this.previous && samePixels(this.previous.pixels, pixels.data)) return;
+ this.flushGif(at);
+ const palette = quantize(pixels.data, 256, { format: 'rgb444' });
+ this.previous = { pixels: pixels.data, palette, index: applyPalette(pixels.data, palette, 'rgb444'), at };
+ if (this.gif.bytesView().length > MAX_RECORDING_BYTES - 4 * 1024 * 1024) this.onLimit();
+ }
+ }
+
+ private flushGif(at: number): void {
+ if (!this.previous || !this.gif) return;
+ this.gif.writeFrame(this.previous.index, this.canvas.width, this.canvas.height, {
+ palette: this.previous.palette, delay: Math.max(20, at - this.previous.at), repeat: 0,
+ });
+ this.previous = null;
+ }
+
+ pause(at: number): void {
+ if (this.recorder?.state === 'recording') this.recorder.pause();
+ this.flushGif(at);
+ }
+ resume(): void { if (this.recorder?.state === 'paused') this.recorder.resume(); }
+
+ async finish(at: number): Promise<Uint8Array<ArrayBuffer>> {
+ if (this.stopped) throw new Error('Recording already stopped');
+ this.stopped = true;
+ if (this.recorder) {
+ await new Promise<void>((resolve, reject) => {
+ const timer = setTimeout(() => { this.stream?.getTracks().forEach((track) => track.stop()); reject(new Error('Recording finalization timed out')); }, 5000);
+ this.recorder!.onstop = () => { clearTimeout(timer); resolve(); };
+ this.recorder!.stop();
+ });
+ this.stream?.getTracks().forEach((track) => track.stop());
+ if (this.failure) throw this.failure;
+ if (!this.bytes) throw new Error('No video frames were encoded');
+ const bytes = finalizeWebmDuration(new Uint8Array(await new Blob(this.chunks, { type: 'video/webm' }).arrayBuffer()), at);
+ if (bytes.length > MAX_RECORDING_BYTES) throw new Error('Recording size limit');
+ return bytes;
+ }
+ this.flushGif(at);
+ this.gif!.finish();
+ const bytes = this.gif!.bytes();
+ if (bytes.length > MAX_RECORDING_BYTES) throw new Error('Recording size limit');
+ return bytes;
+ }
+
+ dispose(): void {
+ this.stopped = true;
+ if (this.recorder && this.recorder.state !== 'inactive') this.recorder.stop();
+ this.stream?.getTracks().forEach((track) => track.stop());
+ this.chunks.length = 0;
+ this.previous = null;
+ }
+}
+
+function samePixels(a: Uint8ClampedArray, b: Uint8ClampedArray): boolean {
+ if (a.length !== b.length) return false;
+ const left = new Uint32Array(a.buffer, a.byteOffset, a.length / 4);
+ const right = new Uint32Array(b.buffer, b.byteOffset, b.length / 4);
+ for (let i = 0; i < left.length; i++) if (left[i] !== right[i]) return false;
+ return true;
+}
diff --git a/apps/desktop/src/renderer/features/region-screenshot/gifenc.d.ts b/apps/desktop/src/renderer/features/region-screenshot/gifenc.d.ts
new file mode 100644
index 0000000000..f27ce114d1
--- /dev/null
+++ b/apps/desktop/src/renderer/features/region-screenshot/gifenc.d.ts
@@ -0,0 +1,10 @@
+declare module 'gifenc' {
+ export function quantize(data: Uint8Array | Uint8ClampedArray, colors: number, options?: { format?: 'rgb565' | 'rgb444' }): number[][];
+ export function applyPalette(data: Uint8Array | Uint8ClampedArray, palette: number[][], format?: 'rgb565' | 'rgb444'): Uint8Array;
+ export function GIFEncoder(): {
+ writeFrame(index: Uint8Array, width: number, height: number, options: { palette: number[][]; delay: number; repeat?: number }): void;
+ finish(): void;
+ bytes(): Uint8Array<ArrayBuffer>;
+ bytesView(): Uint8Array;
+ };
+}
diff --git a/apps/desktop/src/renderer/features/region-screenshot/screenshotColors.ts b/apps/desktop/src/renderer/features/region-screenshot/screenshotColors.ts
new file mode 100644
index 0000000000..ee66a7759d
--- /dev/null
+++ b/apps/desktop/src/renderer/features/region-screenshot/screenshotColors.ts
@@ -0,0 +1,28 @@
+/**
+ * 截图浮层与贴图里不随主题变化的颜色 (DESIGN.md §2「Screenshot overlay and annotation ink」)。
+ *
+ * - SCREENSHOT_INK: 标注墨水, 烧录进用户截图的内容像素, 不是界面配色 (红色即
+ * annotation-accent 的值)。
+ * - SCREENSHOT_OVERLAY: 覆盖在任意屏幕内容上的功能像素 —— 暗化遮罩、选区白描边与暗色
+ * 外圈、放大镜十字线、定格画面底色。它们要在任何底色上都看得清, 两种模式同值。
+ *
+ * 界面 chrome (工具条、放大镜外框与文字、尺寸标签、贴图描边) 一律走主题 token, 不放在这里。
+ */
+export const SCREENSHOT_INK = {
+ red: '#FF3B30',
+ yellow: '#FFCC00',
+ green: '#34C759',
+ blue: '#007AFF',
+ black: '#000000',
+ white: '#FFFFFF',
+} as const;
+
+export type ScreenshotInk = keyof typeof SCREENSHOT_INK;
+
+export const SCREENSHOT_OVERLAY = {
+ backdrop: '#000000',
+ shade: 'rgba(0, 0, 0, 0.45)',
+ edge: '#FFFFFF',
+ edgeOuter: 'rgba(0, 0, 0, 0.6)',
+ crosshair: 'rgba(0, 0, 0, 0.35)',
+} as const;
diff --git a/apps/desktop/src/renderer/features/region-screenshot/screenshotTaskHandoff.ts b/apps/desktop/src/renderer/features/region-screenshot/screenshotTaskHandoff.ts
new file mode 100644
index 0000000000..d8c1735527
--- /dev/null
+++ b/apps/desktop/src/renderer/features/region-screenshot/screenshotTaskHandoff.ts
@@ -0,0 +1,142 @@
+/**
+ * 截图交给新任务 (主窗口侧)。
+ *
+ * main 已把截图按粘贴图片同一条草稿链路入仓, 这里只写 New Maker 草稿:
+ * - 「问 Cindy」: 截图追加到新任务草稿, 保留已有文字与附件, 用户自己写问题再发;
+ * - 「翻译 / 解释 / 提取文字」: 一键出结果 —— 截图 + 预设提示词作为新任务直接发出
+ * (用户点的就是这个动作, 不再叠确认)。发送走输入框的普通发送路径
+ * (requestComposerSubmit), 模型、权限、建任务逻辑都不绕过。用户原来的新任务
+ * 草稿先存下, 发送完成后放回去; 迟迟没发出时把它与截图草稿合并, 不丢内容。
+ *
+ * 发出的消息仍是本机用户亲手触发的输入, 不加消息来源标签 (见
+ * docs/product-rules/message-source.md)。
+ */
+
+import { NEW_MAKER_DRAFT_KEY } from '@/features/cc-agent/newMakerDraftKeys';
+import i18n from '@/i18n';
+import { requestComposerSubmit, takeComposerSubmitRequest } from '@/lib/composerActionsBus';
+import {
+ getDataOwnerGeneration,
+ isDataOwnerIdCurrent,
+ isDataOwnerPushStampCurrent,
+} from '@/contexts/dataOwnerGeneration';
+import {
+ draftHasContent,
+ captureDraftRecoveryScope,
+ getDraft,
+ plainTextToTiptapDoc,
+ saveDraft,
+ type ComposerDraft,
+} from '@/lib/composerDraftStore';
+import type { AttachedFile } from '@/lib/fileTypes';
+import type { RegionScreenshotComposeRequest } from '../../../shared/regionScreenshot';
+
+const RESTORE_POLL_MS = 500;
+const RESTORE_WAIT_MS = 30_000;
+let finishPendingRestore: (() => void) | null = null;
+
+function screenshotAttachment(request: RegionScreenshotComposeRequest): AttachedFile {
+ return {
+ id: crypto.randomUUID(),
+ name: request.filename,
+ // 与剪贴板粘贴的 `clipboard://paste-*` 同型: 图片附件以 url 为准, path 只标识来源。
+ path: `clipboard://screenshot-${request.id}`,
+ ext: '.png',
+ size: request.bytes,
+ category: 'image',
+ mimeType: 'image/png',
+ url: request.url,
+ originalName: request.filename,
+ };
+}
+
+const hasAttachment = (draft: ComposerDraft | undefined, url: string) =>
+ !!draft?.attachments.some((file) => file.url === url);
+
+/** 发送完成 (草稿里不再有这张截图) 后放回用户原来的草稿; 一直没发出则合并两份。 */
+function restoreAfterSend(previous: ComposerDraft, url: string): void {
+ const startedAt = Date.now();
+ const owner = getDataOwnerGeneration();
+ const scope = captureDraftRecoveryScope(NEW_MAKER_DRAFT_KEY);
+ let timer: ReturnType<typeof setTimeout>;
+ const restore = () => {
+ clearTimeout(timer);
+ if (finishPendingRestore === restore) finishPendingRestore = null;
+ if (isDataOwnerIdCurrent(owner)) takeComposerSubmitRequest(NEW_MAKER_DRAFT_KEY);
+ const current = scope.get();
+ if (!draftHasContent(current)) {
+ scope.save(previous);
+ return;
+ }
+ scope.save({
+ ...previous,
+ text: {
+ type: 'doc',
+ content: [...(previous.text?.content ?? []), ...(current?.text?.content ?? [])],
+ },
+ attachments: [
+ ...new Map(
+ [...previous.attachments, ...(current?.attachments ?? [])].map((file) => [
+ file.url ?? file.path,
+ file,
+ ]),
+ ).values(),
+ ],
+ quotes: [...(previous.quotes ?? []), ...(current?.quotes ?? [])],
+ browserComments: [...(previous.browserComments ?? []), ...(current?.browserComments ?? [])],
+ });
+ };
+ finishPendingRestore = restore;
+ const check = () => {
+ if (!isDataOwnerIdCurrent(owner)) {
+ restore();
+ return;
+ }
+ const current = getDraft(NEW_MAKER_DRAFT_KEY);
+ if (!hasAttachment(current, url)) {
+ restore();
+ return;
+ }
+ if (Date.now() - startedAt < RESTORE_WAIT_MS) {
+ timer = setTimeout(check, RESTORE_POLL_MS);
+ return;
+ }
+ restore();
+ };
+ timer = setTimeout(check, RESTORE_POLL_MS);
+}
+
+export function applyScreenshotComposeRequest(
+ request: RegionScreenshotComposeRequest,
+ navigate: (path: string) => void,
+): void {
+ if (!isDataOwnerPushStampCurrent(request.ownerStamp)) return;
+ // 先收回上一轮保管的草稿,再开始下一轮;旧 timer 不能把原稿遗失或覆盖新稿。
+ finishPendingRestore?.();
+ takeComposerSubmitRequest(NEW_MAKER_DRAFT_KEY);
+ const attachment = screenshotAttachment(request);
+ const existing = getDraft(NEW_MAKER_DRAFT_KEY);
+ if (request.action === 'ask') {
+ saveDraft(
+ NEW_MAKER_DRAFT_KEY,
+ {
+ text: existing?.text ?? null,
+ attachments: [...(existing?.attachments ?? []), attachment],
+ quotes: existing?.quotes ?? [],
+ browserComments: existing?.browserComments ?? [],
+ focusAtEnd: true,
+ },
+ { preserveRemoteOptimisticRecovery: true },
+ );
+ navigate('/cc-agent/new');
+ return;
+ }
+ const prompt = i18n.t(`regionScreenshot.prompt.${request.action}`);
+ saveDraft(NEW_MAKER_DRAFT_KEY, {
+ text: plainTextToTiptapDoc(prompt),
+ attachments: [attachment],
+ });
+ navigate('/cc-agent/new');
+ requestComposerSubmit({ storageKey: NEW_MAKER_DRAFT_KEY, attachmentUrl: request.url });
+ if (existing && draftHasContent(existing)) restoreAfterSend(existing, request.url);
+}
diff --git a/apps/desktop/src/renderer/features/region-screenshot/trackpad.ts b/apps/desktop/src/renderer/features/region-screenshot/trackpad.ts
new file mode 100644
index 0000000000..ce22526b79
--- /dev/null
+++ b/apps/desktop/src/renderer/features/region-screenshot/trackpad.ts
@@ -0,0 +1,20 @@
+/**
+ * 触控板与鼠标滚轮的区分 (截图浮层、贴图、编辑窗共用)。
+ *
+ * Chromium 对触控板 / 妙控鼠标的连续滚动给出 `wheelDeltaY === -3 × deltaY`, 鼠标滚轮
+ * 每格是 120 的倍数; 没有 wheelDelta 的环境按像素模式的小数增量判断。macOS 的双指
+ * 捏合以带 ctrlKey 的 wheel 事件送达, deltaY 约为 `-100 × ln(缩放比例)`。
+ */
+export function isPreciseWheel(event: WheelEvent): boolean {
+ const legacy = (event as WheelEvent & { wheelDeltaY?: number }).wheelDeltaY;
+ if (legacy) return legacy === -3 * event.deltaY;
+ return event.deltaMode === 0 && !Number.isInteger(event.deltaY);
+}
+
+/** 捏合手势一次事件对应的缩放倍率 (连续、可叠乘)。 */
+export function pinchZoomFactor(deltaY: number): number {
+ return Math.exp(-Math.max(-50, Math.min(50, deltaY)) / 100);
+}
+
+/** 一次触控板手势结束的判定: 这么久没有新的滚轮事件 (含惯性) 就算新手势。 */
+export const WHEEL_GESTURE_GAP_MS = 220;
diff --git a/apps/desktop/src/renderer/features/region-screenshot/webmDuration.ts b/apps/desktop/src/renderer/features/region-screenshot/webmDuration.ts
new file mode 100644
index 0000000000..7d8f80eb81
--- /dev/null
+++ b/apps/desktop/src/renderer/features/region-screenshot/webmDuration.ts
@@ -0,0 +1,64 @@
+/** MediaRecorder writes a streaming WebM without Duration. Finalize its Info so
+ * local playback and saved files have a finite, seekable timeline. No remuxing or
+ * frame decoding: only the small metadata prefix changes. */
+export function finalizeWebmDuration(bytes: Uint8Array<ArrayBuffer>, milliseconds: number): Uint8Array<ArrayBuffer> {
+ type Element = { id: number; start: number; sizeAt: number; width: number; data: number; end: number; unknown: boolean };
+ function element(start: number, limit: number): Element {
+ let at = start;
+ function vint(id = false) {
+ const first = bytes[at];
+ if (!first) throw new Error('Invalid WebM metadata');
+ let width = 1, marker = 128;
+ while (!(first & marker)) { width++; marker >>= 1; }
+ if (width > (id ? 4 : 8) || at + width > limit) throw new Error('Invalid WebM metadata');
+ let value = id ? first : first & (marker - 1);
+ let unknown = !id && value === marker - 1;
+ for (let i = 1; i < width; i++) { const byte = bytes[at + i]; value = value * 256 + byte; unknown &&= byte === 255; }
+ at += width;
+ return { value, width, unknown };
+ }
+ const id = vint(true).value, sizeAt = at, size = vint();
+ const end = size.unknown ? limit : at + size.value;
+ if (!Number.isSafeInteger(end) || end > limit || end <= start) throw new Error('Invalid WebM metadata');
+ return { id, start, sizeAt, width: size.width, data: at, end, unknown: size.unknown };
+ }
+ function children(start: number, end: number): Element[] {
+ const result: Element[] = [];
+ for (let at = start; at < end;) { const item = element(at, end); result.push(item); at = item.end; }
+ return result;
+ }
+ function join(parts: Uint8Array[]): Uint8Array<ArrayBuffer> {
+ const result = new Uint8Array(parts.reduce((sum, part) => sum + part.length, 0));
+ let offset = 0;
+ for (const part of parts) { result.set(part, offset); offset += part.length; }
+ return result;
+ }
+ function wrap(item: Element, payload: Uint8Array): Uint8Array<ArrayBuffer> {
+ let width = item.width;
+ while (payload.length >= 2 ** (7 * width) - 1) width++;
+ const size = new Uint8Array(width);
+ let value = BigInt(payload.length) | (1n << BigInt(7 * width));
+ for (let i = width - 1; i >= 0; i--) { size[i] = Number(value & 255n); value >>= 8n; }
+ return join([bytes.subarray(item.start, item.sizeAt), item.unknown ? bytes.subarray(item.sizeAt, item.data) : size, payload]);
+ }
+ const segment = children(0, bytes.length).find((item) => item.id === 0x18538067);
+ if (!segment) throw new Error('WebM segment missing');
+ const top = children(segment.data, segment.end);
+ const info = top.find((item) => item.id === 0x1549a966);
+ if (!info) throw new Error('WebM info missing');
+ const metadata = children(info.data, info.end);
+ if (metadata.some((item) => item.id === 0x4489)) return bytes;
+ // This is the streaming MediaRecorder format. Indexed files have offsets that
+ // must not be moved; they already carry final metadata and are not our output.
+ if (top.some((item) => item.id === 0x114d9b74 || item.id === 0x1c53bb6b)) return bytes;
+ const scale = metadata.find((item) => item.id === 0x2ad7b1);
+ let nanoseconds = 1_000_000;
+ if (scale) { nanoseconds = 0; for (let i = scale.data; i < scale.end; i++) nanoseconds = nanoseconds * 256 + bytes[i]; }
+ if (!(nanoseconds > 0) || !Number.isFinite(milliseconds)) throw new Error('Invalid WebM timing');
+ const duration = new Uint8Array(11);
+ duration.set([0x44, 0x89, 0x88]);
+ new DataView(duration.buffer).setFloat64(3, Math.max(1, milliseconds) * 1_000_000 / nanoseconds);
+ const nextInfo = wrap(info, join([bytes.subarray(info.data, info.end), duration]));
+ const nextSegment = wrap(segment, join([bytes.subarray(segment.data, info.start), nextInfo, bytes.subarray(info.end, segment.end)]));
+ return join([bytes.subarray(0, segment.start), nextSegment, bytes.subarray(segment.end)]);
+}
diff --git a/apps/desktop/src/renderer/i18n/locales/en/common.json b/apps/desktop/src/renderer/i18n/locales/en/common.json
index f45b747362..b0b00f41e8 100644
--- a/apps/desktop/src/renderer/i18n/locales/en/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/en/common.json
@@ -74,6 +74,11 @@
"stopped": "The local connection has stopped"
}
},
+ "attachmentAccessConfirmation": {
+ "title": "Confirm Attachment Access",
+ "message": "Cindy cannot read this attachment. Select the original file to continue sending this message. Cancelling keeps your draft.",
+ "button": "Use Original File"
+ },
"mailReader": {
"showExternalImages": "Show External Images",
"markReadFailed": "Could not sync read status. Check mailbox authorization and reopen this email.",
@@ -857,6 +862,135 @@
"deleted": "Deleted the {{provider}} provider group"
}
},
+ "regionScreenshot": {
+ "editor": { "fitWidth": "Fit width", "loading": "Loading image…" },
+ "moveToolbar": "Move toolbar left or right",
+ "hint": "Click to select a window or element, or drag to select an area · Scroll to change scope · Space: full screen · C: copy color · Esc: exit",
+ "hintWithLast": "Click to select a window or element, or drag to select an area · Scroll to change scope · Space: full screen · R: last area · C: copy color · Esc: exit",
+ "copy": "Copy",
+ "cancel": "Exit Screenshot",
+ "captureFailed": "Could not capture the screen",
+ "permission": {
+ "title": "Screen Recording Permission Required",
+ "detail": "To take screenshots, allow {{appName}} in System Settings > Privacy & Security > Screen & System Audio Recording, then reopen {{appName}}.",
+ "openSettings": "Open System Settings",
+ "later": "Not Now"
+ },
+ "undo": "Undo",
+ "redo": "Redo",
+ "pinToScreen": "Pin to Screen",
+ "pin": {
+ "copy": "Copy",
+ "save": "Save…",
+ "ask": "Ask {{appName}}",
+ "opacity": "Opacity",
+ "originalSize": "Original Size",
+ "passThrough": "Click Through",
+ "close": "Close",
+ "closeAll": "Close All Pins",
+ "unlock": "Restore Mouse Input"
+ },
+ "save": "Save",
+ "cindy": "Send to {{appName}}",
+ "tools": {
+ "rect": "Rectangle",
+ "ellipse": "Ellipse",
+ "line": "Line",
+ "arrow": "Arrow",
+ "pen": "Pen",
+ "marker": "Highlighter",
+ "text": "Text",
+ "mosaic": "Mosaic",
+ "blur": "Blur",
+ "step": "Number"
+ },
+ "ai": {
+ "ask": "Ask {{appName}}",
+ "translate": "Translate",
+ "explain": "Explain",
+ "extract": "Extract Text"
+ },
+ "size": {
+ "stroke": {
+ "0": "Thin",
+ "1": "Medium",
+ "2": "Thick"
+ },
+ "text": {
+ "0": "Small",
+ "1": "Medium",
+ "2": "Large"
+ },
+ "strength": {
+ "0": "Light",
+ "1": "Medium",
+ "2": "Strong"
+ }
+ },
+ "colors": {
+ "red": "Red",
+ "yellow": "Yellow",
+ "green": "Green",
+ "blue": "Blue",
+ "black": "Black",
+ "white": "White"
+ },
+ "magnifier": {
+ "copyHint": "C: copy color"
+ },
+ "saveFileName": "Screenshot",
+ "saveFailed": "Couldn't save the screenshot",
+ "prompt": {
+ "translate": "Recognize the text in this screenshot and translate it into English. Keep the original paragraphs and lists, and output only the translation. If the text is already in English, translate it into Simplified Chinese.",
+ "explain": "Explain what this screenshot shows. If it's an error, explain the cause and how to fix it. If it's a chart, code, or an interface, explain what it shows and the key points.",
+ "extract": "Extract the text from this screenshot exactly as written, keeping the original line breaks, paragraphs, and lists. Output tables as Markdown tables. Output only the extracted text."
+ },
+ "live": {
+ "scroll": "Scrolling Screenshot",
+ "video": "Record Screen",
+ "gif": "Record GIF",
+ "recording": "Recording…",
+ "preview": "Capture preview",
+ "cursor": "Show pointer",
+ "keys": "Show keys (includes typing)",
+ "start": "Start Recording",
+ "pause": "Pause",
+ "resume": "Resume",
+ "finish": "Finish",
+ "paused": "Recording paused",
+ "done": "Capture ready to save",
+ "saved": "Saved",
+ "copied": "Copied",
+ "copyFailed": "Could not copy. Try again or save the file.",
+ "scrollHint": "Scroll up or down in the selection, or choose Auto Scroll.",
+ "recordHint": "Draw on the preview to annotate the recording. No audio.",
+ "format": "Format",
+ "videoFormat": "Video (WebM)",
+ "prepareHint": "Starts after a 3-second countdown. No audio.",
+ "countdown": "Recording starts in {{count}}",
+ "countdownHint": "Starting shortly. Press Esc to cancel.",
+ "annotate": "Annotate",
+ "finishing": "Finishing…",
+ "replay": "Replay",
+ "previewUnavailable": "Preview unavailable. Save the clip or close the previous preview and try again.",
+ "playbackFailed": "Playback failed. You can still save the recording.",
+ "annotationNoRoom": "Leave more space beside the selection to open annotations.",
+ "overlap": "This part could not be joined. Scroll back a little, or finish with the captured content.",
+ "limit": "Capture limit reached. Finish and save this capture.",
+ "captureFailed": "Capture stopped. Resume to try again or save the captured portion.",
+ "encodeFailed": "Could not encode this recording. Close and start a new capture.",
+ "exportFailed": "Could not save this capture. Choose Save to try again.",
+ "keysUnavailable": "Key display is unavailable. On macOS, allow Input Monitoring for Cindy.",
+ "noRoom": "Cannot start. Select an area at least 32 × 32 pixels and leave room beside it for the preview.",
+ "image": "Screenshot",
+ "startScroll": "Start Scrolling Screenshot",
+ "autoScroll": "Auto Scroll",
+ "stopScroll": "Stop Scrolling",
+ "edit": "Edit",
+ "autoUnavailable": "Auto scrolling stopped. You can scroll manually in the selection.",
+ "autoPermission": "Auto scrolling needs Accessibility permission. Allow Cindy in System Settings and try again, or scroll manually in the selection."
+ }
+ },
"privacyExit": {
"status": "This computer is being remotely controlled through Cindy",
"hint": "Click or press any key to disconnect…",
@@ -6216,9 +6350,15 @@
"conflict": "Conflicts with \"{{name}}\"",
"voiceConflict": "Conflicts with the voice input shortcut",
"composerVoiceConflict": "Conflicts with the voice input shortcut. Change either the composer send shortcut or the voice input shortcut.",
- "menuAccelerator": "This combination cannot be registered as a menu shortcut"
+ "menuAccelerator": "This combination cannot be registered as a menu shortcut",
+ "globalUnusable": "This combination cannot be used as a system-wide shortcut",
+ "globalOccupied": "Already in use by another app. Choose a different combination."
},
"items": {
+ "region-screenshot": {
+ "label": "Screenshot",
+ "description": "Take a screenshot in any app, then annotate it, pin it to the screen, or send it to {{appName}}"
+ },
"toggle-sidebar": {
"label": "Toggle sidebar",
"description": "Collapse or expand the session list sidebar"
@@ -12990,7 +13130,13 @@
}
},
"ccAgent": {
- "sessionEntry": {"missing":"This session could not be found. It may have been deleted.","denied":"This account or computer cannot access this session.","failed":"Could not load this session.","back":"Back to Sessions","retry":"Reload Session"},
+ "sessionEntry": {
+ "missing": "This session could not be found. It may have been deleted.",
+ "denied": "This account or computer cannot access this session.",
+ "failed": "Could not load this session.",
+ "back": "Back to Sessions",
+ "retry": "Reload Session"
+ },
"contextRingPanel": {
"title": "Context",
"meaning": "What AI can refer to this turn: conversation, instructions and tool results.",
diff --git a/apps/desktop/src/renderer/i18n/locales/ja/common.json b/apps/desktop/src/renderer/i18n/locales/ja/common.json
index 9b578ab7bf..298dcea952 100644
--- a/apps/desktop/src/renderer/i18n/locales/ja/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/ja/common.json
@@ -74,6 +74,11 @@
"stopped": "ローカル接続は停止しています"
}
},
+ "attachmentAccessConfirmation": {
+ "title": "添付ファイルへのアクセスを確認",
+ "message": "Cindy がこの添付ファイルを読み取れません。元のファイルを選択すると、このメッセージの送信を続行します。キャンセルすると下書きが保持されます。",
+ "button": "元のファイルを使用"
+ },
"mailReader": {
"showExternalImages": "外部画像を表示",
"markReadFailed": "既読状態を同期できませんでした。メールボックスの認証を確認して開き直してください。",
@@ -845,6 +850,135 @@
"deleted": "{{provider}} のプロバイダーグループを削除しました"
}
},
+ "regionScreenshot": {
+ "editor": { "fitWidth": "幅に合わせる", "loading": "画像を読み込み中…" },
+ "moveToolbar": "ツールバーを左右に移動",
+ "hint": "クリックでウィンドウや要素を選択、ドラッグで範囲を選択 · スクロールで範囲を切り替え · Space で全画面 · C で色をコピー · Esc で終了",
+ "hintWithLast": "クリックでウィンドウや要素を選択、ドラッグで範囲を選択 · スクロールで範囲を切り替え · Space で全画面 · R で前回の範囲 · C で色をコピー · Esc で終了",
+ "copy": "コピー",
+ "cancel": "スクリーンショットを終了",
+ "captureFailed": "画面をキャプチャできませんでした",
+ "permission": {
+ "title": "画面収録の許可が必要です",
+ "detail": "スクリーンショットを撮るには、「システム設定 > プライバシーとセキュリティ > 画面収録とシステムオーディオ録音」で {{appName}} を許可し、{{appName}} を開き直してください。",
+ "openSettings": "システム設定を開く",
+ "later": "今はしない"
+ },
+ "undo": "取り消す",
+ "redo": "やり直す",
+ "pinToScreen": "画面に固定",
+ "pin": {
+ "copy": "コピー",
+ "save": "保存…",
+ "ask": "{{appName}} に聞く",
+ "opacity": "不透明度",
+ "originalSize": "元のサイズ",
+ "passThrough": "クリックを透過",
+ "close": "閉じる",
+ "closeAll": "固定した画像をすべて閉じる",
+ "unlock": "マウス操作を戻す"
+ },
+ "save": "保存",
+ "cindy": "{{appName}} に送る",
+ "tools": {
+ "rect": "四角形",
+ "ellipse": "楕円",
+ "line": "直線",
+ "arrow": "矢印",
+ "pen": "ペン",
+ "marker": "蛍光ペン",
+ "text": "テキスト",
+ "mosaic": "モザイク",
+ "blur": "ぼかし",
+ "step": "番号"
+ },
+ "ai": {
+ "ask": "{{appName}} に聞く",
+ "translate": "翻訳",
+ "explain": "説明",
+ "extract": "テキストを抽出"
+ },
+ "size": {
+ "stroke": {
+ "0": "細",
+ "1": "中",
+ "2": "太"
+ },
+ "text": {
+ "0": "小",
+ "1": "中",
+ "2": "大"
+ },
+ "strength": {
+ "0": "弱",
+ "1": "中",
+ "2": "強"
+ }
+ },
+ "colors": {
+ "red": "赤",
+ "yellow": "黄",
+ "green": "緑",
+ "blue": "青",
+ "black": "黒",
+ "white": "白"
+ },
+ "magnifier": {
+ "copyHint": "C で色をコピー"
+ },
+ "saveFileName": "スクリーンショット",
+ "saveFailed": "スクリーンショットを保存できませんでした",
+ "prompt": {
+ "translate": "このスクリーンショットの文字を読み取り、日本語に翻訳してください。元の段落やリストの構成を保ち、訳文だけを出力してください。原文がすでに日本語の場合は英語に翻訳してください。",
+ "explain": "このスクリーンショットの内容を説明してください。エラーの場合は原因と解決方法を、グラフ・コード・画面の場合は何を表しているかと要点を説明してください。",
+ "extract": "このスクリーンショットの文字をそのまま抽出してください。元の改行・段落・リストを保ち、表は Markdown の表で出力してください。抽出した文字だけを出力してください。"
+ },
+ "live": {
+ "scroll": "スクロールスクリーンショット",
+ "video": "画面録画",
+ "gif": "GIF を録画",
+ "recording": "録画中…",
+ "preview": "キャプチャのプレビュー",
+ "cursor": "ポインターを表示",
+ "keys": "キーを表示(入力内容を含む)",
+ "start": "録画を開始",
+ "pause": "一時停止",
+ "resume": "再開",
+ "finish": "完了",
+ "paused": "録画を一時停止しました",
+ "done": "キャプチャを保存できます",
+ "saved": "保存しました",
+ "copied": "コピーしました",
+ "copyFailed": "コピーできませんでした。もう一度試すか、ファイルを保存してください。",
+ "scrollHint": "選択範囲内を上下にスクロールするか、自動スクロールを選択してください",
+ "recordHint": "プレビューに描いた注釈は録画に含まれます。音声は録音しません。",
+ "format": "形式",
+ "videoFormat": "動画 (WebM)",
+ "prepareHint": "開始を押すと3秒後に録画します。音声は録音しません。",
+ "countdown": "{{count}}秒後に録画開始",
+ "countdownHint": "まもなく開始します。Escでキャンセル。",
+ "annotate": "注釈",
+ "finishing": "処理中…",
+ "replay": "もう一度再生",
+ "previewUnavailable": "プレビューを開けません。保存するか、前のプレビューを閉じて再試行してください。",
+ "playbackFailed": "再生できません。録画ファイルは保存できます。",
+ "annotationNoRoom": "注釈を開くには選択範囲の横に空き領域が必要です。",
+ "overlap": "この部分を結合できません。少し上に戻すか、撮影済みの部分で完了してください。",
+ "limit": "キャプチャの上限に達しました。終了して保存してください。",
+ "captureFailed": "キャプチャが停止しました。再開するか、取得済みの内容を保存できます。",
+ "encodeFailed": "録画をエンコードできませんでした。閉じてから録画し直してください。",
+ "exportFailed": "保存できませんでした。もう一度保存を選んでください。",
+ "keysUnavailable": "キーを表示できません。macOS では Cindy の入力監視を許可してください。",
+ "noRoom": "開始できません。32 × 32 ピクセル以上の範囲を選択し、その横にプレビュー用のスペースを空けてください。",
+ "image": "スクリーンショット",
+ "startScroll": "スクロールスクリーンショットを開始",
+ "autoScroll": "自動スクロール",
+ "stopScroll": "スクロールを停止",
+ "edit": "編集",
+ "autoUnavailable": "自動スクロールが停止しました。選択範囲内を手動でスクロールできます。",
+ "autoPermission": "自動スクロールには「アクセシビリティ」の権限が必要です。システム設定で Cindy を許可してから再試行するか、選択範囲内を手動でスクロールしてください。"
+ }
+ },
"privacyExit": {
"status": "Cindy でリモート操作されています",
"hint": "クリックまたは任意のキーを押すと、切断を確認できます",
@@ -6185,9 +6319,15 @@
"conflict": "「{{name}}」と競合しています",
"voiceConflict": "音声入力のショートカットと競合しています",
"composerVoiceConflict": "音声入力のショートカットと競合しています。メッセージ入力の送信ショートカットまたは音声入力のショートカットを変更してください。",
- "menuAccelerator": "この組み合わせはメニューショートカットとして登録できません"
+ "menuAccelerator": "この組み合わせはメニューショートカットとして登録できません",
+ "globalUnusable": "この組み合わせはシステム全体のショートカットに使用できません",
+ "globalOccupied": "他のアプリで使用中です。別の組み合わせを選んでください"
},
"items": {
+ "region-screenshot": {
+ "label": "スクリーンショット",
+ "description": "どのアプリでもスクリーンショットを撮り、注釈を付けたり、画面に固定したり、{{appName}} に送ったりできます"
+ },
"toggle-sidebar": {
"label": "サイドバーを切り替え",
"description": "左側のセッションリストを折りたたみ・展開します"
@@ -12936,7 +13076,13 @@
}
},
"ccAgent": {
- "sessionEntry": {"missing":"このセッションが見つかりません。削除された可能性があります。","denied":"このアカウントまたはコンピューターでは、このセッションにアクセスできません。","failed":"このセッションを読み込めませんでした。","back":"セッション一覧に戻る","retry":"セッションを再読み込み"},
+ "sessionEntry": {
+ "missing": "このセッションが見つかりません。削除された可能性があります。",
+ "denied": "このアカウントまたはコンピューターでは、このセッションにアクセスできません。",
+ "failed": "このセッションを読み込めませんでした。",
+ "back": "セッション一覧に戻る",
+ "retry": "セッションを再読み込み"
+ },
"contextRingPanel": {
"title": "コンテキスト",
"meaning": "今回 AI が参照できる会話、指示、ツールの結果です。",
diff --git a/apps/desktop/src/renderer/i18n/locales/ko/common.json b/apps/desktop/src/renderer/i18n/locales/ko/common.json
index 5e887a5d47..536991f92d 100644
--- a/apps/desktop/src/renderer/i18n/locales/ko/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/ko/common.json
@@ -74,6 +74,11 @@
"stopped": "로컬 연결이 중지되었습니다"
}
},
+ "attachmentAccessConfirmation": {
+ "title": "첨부 파일 접근 확인",
+ "message": "Cindy가 이 첨부 파일을 읽을 수 없습니다. 원본 파일을 선택하면 이 메시지 전송을 계속합니다. 취소하면 초안이 유지됩니다.",
+ "button": "원본 파일 사용"
+ },
"mailReader": {
"showExternalImages": "외부 이미지 표시",
"markReadFailed": "읽음 상태를 동기화하지 못했습니다. 메일함 인증을 확인하고 다시 여세요.",
@@ -845,6 +850,135 @@
"deleted": "{{provider}} 제공자 그룹을 삭제했습니다"
}
},
+ "regionScreenshot": {
+ "editor": { "fitWidth": "너비에 맞추기", "loading": "이미지를 불러오는 중…" },
+ "moveToolbar": "도구 모음을 좌우로 이동",
+ "hint": "클릭하여 창이나 요소 선택, 드래그하여 영역 선택 · 스크롤로 범위 변경 · Space 전체 화면 · C 색상 복사 · Esc 종료",
+ "hintWithLast": "클릭하여 창이나 요소 선택, 드래그하여 영역 선택 · 스크롤로 범위 변경 · Space 전체 화면 · R 이전 영역 · C 색상 복사 · Esc 종료",
+ "copy": "복사",
+ "cancel": "스크린샷 종료",
+ "captureFailed": "화면을 캡처하지 못했습니다",
+ "permission": {
+ "title": "화면 기록 권한이 필요합니다",
+ "detail": "스크린샷을 찍으려면 시스템 설정 > 개인정보 보호 및 보안 > 화면 및 시스템 오디오 기록에서 {{appName}}을(를) 허용한 다음 {{appName}}을(를) 다시 여세요.",
+ "openSettings": "시스템 설정 열기",
+ "later": "나중에"
+ },
+ "undo": "실행 취소",
+ "redo": "다시 실행",
+ "pinToScreen": "화면에 고정",
+ "pin": {
+ "copy": "복사",
+ "save": "저장…",
+ "ask": "{{appName}}에 묻기",
+ "opacity": "불투명도",
+ "originalSize": "원래 크기",
+ "passThrough": "마우스 클릭 통과",
+ "close": "닫기",
+ "closeAll": "고정한 이미지 모두 닫기",
+ "unlock": "마우스 조작 복원"
+ },
+ "save": "저장",
+ "cindy": "{{appName}}에 보내기",
+ "tools": {
+ "rect": "사각형",
+ "ellipse": "타원",
+ "line": "직선",
+ "arrow": "화살표",
+ "pen": "펜",
+ "marker": "형광펜",
+ "text": "텍스트",
+ "mosaic": "모자이크",
+ "blur": "흐리게",
+ "step": "번호"
+ },
+ "ai": {
+ "ask": "{{appName}}에 묻기",
+ "translate": "번역",
+ "explain": "설명",
+ "extract": "텍스트 추출"
+ },
+ "size": {
+ "stroke": {
+ "0": "가늘게",
+ "1": "보통",
+ "2": "굵게"
+ },
+ "text": {
+ "0": "작게",
+ "1": "보통",
+ "2": "크게"
+ },
+ "strength": {
+ "0": "약하게",
+ "1": "보통",
+ "2": "강하게"
+ }
+ },
+ "colors": {
+ "red": "빨간색",
+ "yellow": "노란색",
+ "green": "초록색",
+ "blue": "파란색",
+ "black": "검은색",
+ "white": "흰색"
+ },
+ "magnifier": {
+ "copyHint": "C 색상 복사"
+ },
+ "saveFileName": "스크린샷",
+ "saveFailed": "스크린샷을 저장하지 못했습니다",
+ "prompt": {
+ "translate": "이 스크린샷의 텍스트를 인식해 한국어로 번역해 주세요. 원래의 문단과 목록 구조를 유지하고 번역문만 출력해 주세요. 원문이 이미 한국어라면 영어로 번역해 주세요.",
+ "explain": "이 스크린샷의 내용을 설명해 주세요. 오류라면 원인과 해결 방법을, 차트·코드·화면이라면 무엇을 나타내는지와 핵심 내용을 설명해 주세요.",
+ "extract": "이 스크린샷의 텍스트를 그대로 추출해 주세요. 원래의 줄바꿈, 문단, 목록을 유지하고 표는 Markdown 표로 출력해 주세요. 추출한 텍스트만 출력해 주세요."
+ },
+ "live": {
+ "scroll": "스크롤 스크린샷",
+ "video": "화면 녹화",
+ "gif": "GIF 녹화",
+ "recording": "녹화 중…",
+ "preview": "캡처 미리 보기",
+ "cursor": "포인터 표시",
+ "keys": "키 표시 (입력 내용 포함)",
+ "start": "녹화 시작",
+ "pause": "일시 정지",
+ "resume": "계속",
+ "finish": "완료",
+ "paused": "녹화가 일시 정지되었습니다",
+ "done": "캡처를 저장할 수 있습니다",
+ "saved": "저장됨",
+ "copied": "복사됨",
+ "copyFailed": "복사하지 못했습니다. 다시 시도하거나 파일을 저장하세요.",
+ "scrollHint": "선택 영역에서 위아래로 스크롤하거나 자동 스크롤을 선택하세요",
+ "recordHint": "미리 보기에 그린 주석은 녹화에 포함됩니다. 소리는 녹음하지 않습니다.",
+ "format": "형식",
+ "videoFormat": "동영상 (WebM)",
+ "prepareHint": "시작을 누르면 3초 후 녹화됩니다. 소리는 녹음하지 않습니다.",
+ "countdown": "{{count}}초 후 녹화 시작",
+ "countdownHint": "곧 시작합니다. Esc를 누르면 취소됩니다.",
+ "annotate": "주석",
+ "finishing": "완료 처리 중…",
+ "replay": "다시 재생",
+ "previewUnavailable": "미리보기를 열 수 없습니다. 저장하거나 이전 미리보기를 닫고 다시 시도하세요.",
+ "playbackFailed": "재생할 수 없습니다. 녹화 파일은 저장할 수 있습니다.",
+ "annotationNoRoom": "주석을 펼치려면 선택 영역 옆에 여유 공간이 필요합니다.",
+ "overlap": "이 부분을 연결하지 못했습니다. 조금 위로 스크롤하거나 지금까지 캡처한 내용으로 완료하세요.",
+ "limit": "캡처 한도에 도달했습니다. 완료하고 저장하세요.",
+ "captureFailed": "캡처가 중지되었습니다. 다시 시작하거나 캡처된 내용을 저장할 수 있습니다.",
+ "encodeFailed": "녹화를 인코딩하지 못했습니다. 닫은 뒤 다시 녹화하세요.",
+ "exportFailed": "저장하지 못했습니다. 저장을 다시 선택하세요.",
+ "keysUnavailable": "키를 표시할 수 없습니다. macOS에서는 Cindy의 입력 모니터링을 허용하세요.",
+ "noRoom": "시작할 수 없습니다. 32 × 32 픽셀 이상의 영역을 선택하고 옆에 미리보기 공간을 남겨 주세요.",
+ "image": "스크린샷",
+ "startScroll": "스크롤 스크린샷 시작",
+ "autoScroll": "자동 스크롤",
+ "stopScroll": "스크롤 중지",
+ "edit": "편집",
+ "autoUnavailable": "자동 스크롤이 중지되었습니다. 선택 영역에서 직접 스크롤할 수 있습니다.",
+ "autoPermission": "자동 스크롤에는 '손쉬운 사용' 권한이 필요합니다. 시스템 설정에서 Cindy를 허용한 후 다시 시도하거나 선택 영역에서 직접 스크롤하세요."
+ }
+ },
"privacyExit": {
"status": "Cindy를 통해 원격 제어 중입니다",
"hint": "화면을 클릭하거나 아무 키나 누르면 연결 끊기를 확인합니다",
@@ -6185,9 +6319,15 @@
"conflict": "\"{{name}}\"과(와) 충돌합니다",
"voiceConflict": "음성 입력 단축키와 충돌합니다",
"composerVoiceConflict": "음성 입력 단축키와 충돌합니다. 메시지 입력의 보내기 단축키 또는 음성 입력 단축키를 변경하세요.",
- "menuAccelerator": "이 조합은 메뉴 단축키로 등록할 수 없습니다"
+ "menuAccelerator": "이 조합은 메뉴 단축키로 등록할 수 없습니다",
+ "globalUnusable": "이 조합은 시스템 전체 단축키로 사용할 수 없습니다",
+ "globalOccupied": "다른 앱에서 사용 중입니다. 다른 조합을 선택하세요"
},
"items": {
+ "region-screenshot": {
+ "label": "스크린샷",
+ "description": "어떤 앱에서든 스크린샷을 찍고 주석을 달거나, 화면에 고정하거나, {{appName}}에 보낼 수 있습니다"
+ },
"toggle-sidebar": {
"label": "사이드바 전환",
"description": "왼쪽 세션 목록을 접거나 펼칩니다"
@@ -12936,7 +13076,13 @@
}
},
"ccAgent": {
- "sessionEntry": {"missing":"이 세션을 찾을 수 없습니다. 삭제되었을 수 있습니다.","denied":"현재 계정 또는 컴퓨터에서 이 세션에 접근할 수 없습니다.","failed":"이 세션을 불러오지 못했습니다.","back":"세션 목록으로 돌아가기","retry":"세션 다시 불러오기"},
+ "sessionEntry": {
+ "missing": "이 세션을 찾을 수 없습니다. 삭제되었을 수 있습니다.",
+ "denied": "현재 계정 또는 컴퓨터에서 이 세션에 접근할 수 없습니다.",
+ "failed": "이 세션을 불러오지 못했습니다.",
+ "back": "세션 목록으로 돌아가기",
+ "retry": "세션 다시 불러오기"
+ },
"contextRingPanel": {
"title": "컨텍스트",
"meaning": "이번 턴에 AI가 참고할 수 있는 대화, 지시 및 도구 결과입니다.",
diff --git a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
index cfb8b9aee7..24bd342bc9 100644
--- a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
@@ -74,6 +74,11 @@
"stopped": "本机连接已停止"
}
},
+ "attachmentAccessConfirmation": {
+ "title": "确认附件访问",
+ "message": "Cindy 无法读取这个附件。请选择原文件,确认后继续发送这条消息;取消会保留草稿。",
+ "button": "使用原文件"
+ },
"mailReader": {
"showExternalImages": "显示外部图片",
"markReadFailed": "未能同步已读状态,请检查邮箱授权后重新打开。",
@@ -845,6 +850,135 @@
"deleted": "已删除 {{provider}} 的供应商组"
}
},
+ "regionScreenshot": {
+ "editor": { "fitWidth": "适合宽度", "loading": "正在加载图片…" },
+ "moveToolbar": "左右拖动工具栏",
+ "hint": "单击选中窗口或元素,拖动框选 · 滚轮切换范围 · 空格全屏 · C 复制颜色 · Esc 退出",
+ "hintWithLast": "单击选中窗口或元素,拖动框选 · 滚轮切换范围 · 空格全屏 · R 上次区域 · C 复制颜色 · Esc 退出",
+ "copy": "复制",
+ "cancel": "退出截图",
+ "captureFailed": "未能截取屏幕",
+ "permission": {
+ "title": "需要屏幕录制权限",
+ "detail": "截图需要在“系统设置 > 隐私与安全性 > 屏幕与系统录音”中允许 {{appName}},开启后重新打开 {{appName}}。",
+ "openSettings": "打开系统设置",
+ "later": "暂不开启"
+ },
+ "undo": "撤销",
+ "redo": "重做",
+ "pinToScreen": "贴到屏幕",
+ "pin": {
+ "copy": "复制",
+ "save": "保存…",
+ "ask": "问 {{appName}}",
+ "opacity": "不透明度",
+ "originalSize": "原始大小",
+ "passThrough": "鼠标穿透",
+ "close": "关闭",
+ "closeAll": "关闭全部贴图",
+ "unlock": "恢复鼠标操作"
+ },
+ "save": "保存",
+ "cindy": "交给 {{appName}}",
+ "tools": {
+ "rect": "矩形",
+ "ellipse": "椭圆",
+ "line": "直线",
+ "arrow": "箭头",
+ "pen": "画笔",
+ "marker": "荧光笔",
+ "text": "文字",
+ "mosaic": "马赛克",
+ "blur": "模糊",
+ "step": "序号"
+ },
+ "ai": {
+ "ask": "问 {{appName}}",
+ "translate": "翻译",
+ "explain": "解释",
+ "extract": "提取文字"
+ },
+ "size": {
+ "stroke": {
+ "0": "细",
+ "1": "中",
+ "2": "粗"
+ },
+ "text": {
+ "0": "小号",
+ "1": "中号",
+ "2": "大号"
+ },
+ "strength": {
+ "0": "弱",
+ "1": "中",
+ "2": "强"
+ }
+ },
+ "colors": {
+ "red": "红色",
+ "yellow": "黄色",
+ "green": "绿色",
+ "blue": "蓝色",
+ "black": "黑色",
+ "white": "白色"
+ },
+ "magnifier": {
+ "copyHint": "C 复制颜色"
+ },
+ "saveFileName": "截图",
+ "saveFailed": "未能保存截图",
+ "prompt": {
+ "translate": "请识别这张截图中的文字并翻译成简体中文,保留原有的段落和列表结构,只输出译文。如果原文已经是中文,就翻译成英文。",
+ "explain": "请解释这张截图的内容。如果是报错,说明原因和解决办法;如果是图表、代码或界面,说明它在表达什么、有哪些要点。",
+ "extract": "请把这张截图中的文字原样提取出来,保留原有的换行、段落和列表;表格用 Markdown 表格输出。只输出提取的文字。"
+ },
+ "live": {
+ "scroll": "滚动截图",
+ "video": "录屏",
+ "gif": "录制 GIF",
+ "recording": "正在录制…",
+ "preview": "采集预览",
+ "cursor": "显示鼠标指针",
+ "keys": "显示按键(包含输入内容)",
+ "start": "开始录制",
+ "pause": "暂停",
+ "resume": "继续",
+ "finish": "完成",
+ "paused": "录制已暂停",
+ "done": "采集完成,可以保存",
+ "saved": "已保存",
+ "copied": "已复制",
+ "copyFailed": "复制失败,可以重试或保存文件。",
+ "scrollHint": "在选区内向上或向下滚动,也可点击自动滚动",
+ "recordHint": "在预览上绘制标注,标注会进入录像。不录制声音",
+ "format": "格式",
+ "videoFormat": "视频 (WebM)",
+ "prepareHint": "点击开始后倒计时 3 秒,不录制声音。",
+ "countdown": "{{count}} 秒后开始录制",
+ "countdownHint": "即将开始,按 Esc 取消。",
+ "annotate": "标注",
+ "finishing": "正在完成…",
+ "replay": "重新播放",
+ "previewUnavailable": "无法打开预览。可直接保存,或关闭上一个预览后重试。",
+ "playbackFailed": "无法播放,仍可保存录制文件。",
+ "annotationNoRoom": "选区旁空间不足,无法展开标注。",
+ "overlap": "这一段未能接上。可稍往回滚动,或完成已截取的部分。",
+ "limit": "已达到采集上限,请完成并保存这段内容",
+ "captureFailed": "采集已停止,可以继续重试或保存已采集内容",
+ "encodeFailed": "录制内容编码失败,请关闭后重新录制",
+ "exportFailed": "保存失败,请再次选择保存",
+ "keysUnavailable": "按键显示不可用。macOS 请为 Cindy 开启输入监控权限",
+ "noRoom": "无法开始。请框选至少 32 × 32 像素的区域,并在选区旁留出预览空间。",
+ "image": "截图",
+ "startScroll": "开始滚动截图",
+ "autoScroll": "自动滚动",
+ "stopScroll": "停止滚动",
+ "edit": "编辑",
+ "autoUnavailable": "自动滚动已停止,可在选区内手动滚动",
+ "autoPermission": "自动滚动需要「辅助功能」权限。请在系统设置中允许 Cindy 后再试,也可以在选区内手动滚动"
+ }
+ },
"privacyExit": {
"status": "正在通过 Cindy 被远程控制",
"hint": "点击屏幕或按任意键,确认后断开连接",
@@ -6179,9 +6313,15 @@
"conflict": "与「{{name}}」冲突",
"voiceConflict": "与语音输入快捷键冲突",
"composerVoiceConflict": "与语音输入快捷键冲突,请修改发送或语音输入快捷键。",
- "menuAccelerator": "该组合键无法注册为菜单快捷键"
+ "menuAccelerator": "该组合键无法注册为菜单快捷键",
+ "globalUnusable": "该组合键不能用作全局快捷键",
+ "globalOccupied": "已被其他应用占用,请换一个组合键"
},
"items": {
+ "region-screenshot": {
+ "label": "截图",
+ "description": "在任意应用中截图,可以标注、贴到屏幕,或交给 {{appName}} 处理"
+ },
"toggle-sidebar": {
"label": "切换侧边栏",
"description": "收起或展开左侧任务列表"
@@ -12936,7 +13076,13 @@
}
},
"ccAgent": {
- "sessionEntry": {"missing":"找不到这条任务,它可能已被删除。","denied":"当前账号或电脑无法访问这条任务。","failed":"未能加载这条任务。","back":"返回任务列表","retry":"重新加载任务"},
+ "sessionEntry": {
+ "missing": "找不到这条任务,它可能已被删除。",
+ "denied": "当前账号或电脑无法访问这条任务。",
+ "failed": "未能加载这条任务。",
+ "back": "返回任务列表",
+ "retry": "重新加载任务"
+ },
"contextRingPanel": {
"title": "上下文",
"meaning": "AI 本轮能参考的内容,包括对话、指令和工具结果。",
diff --git a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
index 342e1a0b53..4c7c0c0d1d 100644
--- a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
@@ -74,6 +74,11 @@
"stopped": "本機連線已停止"
}
},
+ "attachmentAccessConfirmation": {
+ "title": "確認附件存取",
+ "message": "Cindy 無法讀取這個附件。請選擇原始檔案,確認後繼續傳送這則訊息;取消會保留草稿。",
+ "button": "使用原始檔案"
+ },
"mailReader": {
"showExternalImages": "顯示外部圖片",
"markReadFailed": "未能同步已讀狀態,請檢查信箱授權後重新開啟。",
@@ -845,6 +850,135 @@
"deleted": "已刪除 {{provider}} 的供應商組"
}
},
+ "regionScreenshot": {
+ "editor": { "fitWidth": "適合寬度", "loading": "正在載入圖片…" },
+ "moveToolbar": "左右拖動工具列",
+ "hint": "按一下選取視窗或元素,拖曳框選 · 滾輪切換範圍 · 空白鍵全螢幕 · C 複製顏色 · Esc 結束",
+ "hintWithLast": "按一下選取視窗或元素,拖曳框選 · 滾輪切換範圍 · 空白鍵全螢幕 · R 上次區域 · C 複製顏色 · Esc 結束",
+ "copy": "複製",
+ "cancel": "結束截圖",
+ "captureFailed": "無法擷取螢幕",
+ "permission": {
+ "title": "需要螢幕錄製權限",
+ "detail": "截圖需要在「系統設定 > 隱私權與安全性 > 螢幕與系統錄音」中允許 {{appName}},開啟後請重新開啟 {{appName}}。",
+ "openSettings": "打開系統設定",
+ "later": "暫不開啟"
+ },
+ "undo": "復原",
+ "redo": "重做",
+ "pinToScreen": "釘選到螢幕",
+ "pin": {
+ "copy": "複製",
+ "save": "儲存…",
+ "ask": "問 {{appName}}",
+ "opacity": "不透明度",
+ "originalSize": "原始大小",
+ "passThrough": "滑鼠穿透",
+ "close": "關閉",
+ "closeAll": "關閉所有釘選圖片",
+ "unlock": "恢復滑鼠操作"
+ },
+ "save": "儲存",
+ "cindy": "交給 {{appName}}",
+ "tools": {
+ "rect": "矩形",
+ "ellipse": "橢圓",
+ "line": "直線",
+ "arrow": "箭頭",
+ "pen": "畫筆",
+ "marker": "螢光筆",
+ "text": "文字",
+ "mosaic": "馬賽克",
+ "blur": "模糊",
+ "step": "編號"
+ },
+ "ai": {
+ "ask": "問 {{appName}}",
+ "translate": "翻譯",
+ "explain": "解釋",
+ "extract": "擷取文字"
+ },
+ "size": {
+ "stroke": {
+ "0": "細",
+ "1": "中",
+ "2": "粗"
+ },
+ "text": {
+ "0": "小",
+ "1": "中",
+ "2": "大"
+ },
+ "strength": {
+ "0": "弱",
+ "1": "中",
+ "2": "強"
+ }
+ },
+ "colors": {
+ "red": "紅色",
+ "yellow": "黃色",
+ "green": "綠色",
+ "blue": "藍色",
+ "black": "黑色",
+ "white": "白色"
+ },
+ "magnifier": {
+ "copyHint": "C 複製顏色"
+ },
+ "saveFileName": "截圖",
+ "saveFailed": "無法儲存截圖",
+ "prompt": {
+ "translate": "請辨識這張截圖中的文字並翻譯成繁體中文,保留原有的段落和清單結構,只輸出譯文。如果原文已經是中文,就翻譯成英文。",
+ "explain": "請解釋這張截圖的內容。如果是錯誤訊息,說明原因與解決方法;如果是圖表、程式碼或介面,說明它在表達什麼、有哪些重點。",
+ "extract": "請將這張截圖中的文字原樣擷取出來,保留原有的換行、段落和清單;表格以 Markdown 表格輸出。只輸出擷取的文字。"
+ },
+ "live": {
+ "scroll": "捲動截圖",
+ "video": "錄影",
+ "gif": "錄製 GIF",
+ "recording": "正在錄製…",
+ "preview": "擷取預覽",
+ "cursor": "顯示滑鼠指標",
+ "keys": "顯示按鍵(包含輸入內容)",
+ "start": "開始錄製",
+ "pause": "暫停",
+ "resume": "繼續",
+ "finish": "完成",
+ "paused": "錄影已暫停",
+ "done": "擷取完成,可以儲存",
+ "saved": "已儲存",
+ "copied": "已複製",
+ "copyFailed": "複製失敗,可以重試或儲存檔案。",
+ "scrollHint": "在選取範圍內向上或向下捲動,也可點擊自動捲動",
+ "recordHint": "在預覽上繪製標註,標註會出現在錄影中。不錄製聲音",
+ "format": "格式",
+ "videoFormat": "影片 (WebM)",
+ "prepareHint": "點擊開始後倒數 3 秒,不錄製聲音。",
+ "countdown": "{{count}} 秒後開始錄製",
+ "countdownHint": "即將開始,按 Esc 取消。",
+ "annotate": "標註",
+ "finishing": "正在完成…",
+ "replay": "重新播放",
+ "previewUnavailable": "無法開啟預覽。可直接儲存,或關閉上一個預覽後重試。",
+ "playbackFailed": "無法播放,仍可儲存錄製檔案。",
+ "annotationNoRoom": "選取區域旁空間不足,無法展開標註。",
+ "overlap": "這一段未能接上。可稍往回捲動,或完成已擷取的部分。",
+ "limit": "已達擷取上限,請完成並儲存這段內容",
+ "captureFailed": "擷取已停止,可以繼續重試或儲存已擷取內容",
+ "encodeFailed": "錄製內容編碼失敗,請關閉後重新錄製",
+ "exportFailed": "儲存失敗,請再次選擇儲存",
+ "keysUnavailable": "按鍵顯示無法使用。macOS 請為 Cindy 開啟輸入監控權限",
+ "noRoom": "無法開始。請選取至少 32 × 32 像素的範圍,並在旁邊留出預覽空間。",
+ "image": "截圖",
+ "startScroll": "開始捲動截圖",
+ "autoScroll": "自動捲動",
+ "stopScroll": "停止捲動",
+ "edit": "編輯",
+ "autoUnavailable": "自動捲動已停止,可在選取範圍內手動捲動",
+ "autoPermission": "自動捲動需要「輔助使用」權限。請在系統設定中允許 Cindy 後再試,也可以在選取範圍內手動捲動"
+ }
+ },
"privacyExit": {
"status": "正在透過 Cindy 被遠端控制",
"hint": "點擊螢幕或按任意鍵,確認後中斷連線",
@@ -6185,9 +6319,15 @@
"conflict": "與「{{name}}」衝突",
"voiceConflict": "與語音輸入快捷鍵衝突",
"composerVoiceConflict": "與語音輸入快捷鍵衝突,請修改傳送或語音輸入快捷鍵。",
- "menuAccelerator": "該組合鍵無法註冊為選單快捷鍵"
+ "menuAccelerator": "該組合鍵無法註冊為選單快捷鍵",
+ "globalUnusable": "此組合鍵不能用作全域快捷鍵",
+ "globalOccupied": "已被其他應用程式佔用,請換一個組合鍵"
},
"items": {
+ "region-screenshot": {
+ "label": "截圖",
+ "description": "在任何應用程式中截圖,可以加上標註、釘選到螢幕,或交給 {{appName}} 處理"
+ },
"toggle-sidebar": {
"label": "切換側邊欄",
"description": "收起或展開左側任務列表"
@@ -12936,7 +13076,13 @@
}
},
"ccAgent": {
- "sessionEntry": {"missing":"找不到這條任務,它可能已被刪除。","denied":"目前帳號或電腦無法存取這條任務。","failed":"未能載入這條任務。","back":"返回任務列表","retry":"重新載入任務"},
+ "sessionEntry": {
+ "missing": "找不到這條任務,它可能已被刪除。",
+ "denied": "目前帳號或電腦無法存取這條任務。",
+ "failed": "未能載入這條任務。",
+ "back": "返回任務列表",
+ "retry": "重新載入任務"
+ },
"contextRingPanel": {
"title": "上下文",
"meaning": "AI 本輪可參考的內容,包括對話、指令與工具結果。",
diff --git a/apps/desktop/src/renderer/index.tsx b/apps/desktop/src/renderer/index.tsx
index 82e30ba68a..56e8096393 100644
--- a/apps/desktop/src/renderer/index.tsx
+++ b/apps/desktop/src/renderer/index.tsx
@@ -1,23 +1,35 @@
/**
* Renderer 模块图分发入口。
*
- * 资源用量窗口、右侧栏独立子窗口与主应用共用同一个受信任 HTML/origin,
- * 但从这里开始加载不同的模块图。判断必须发生在任何主应用静态依赖之前,
- * 否则 ESM 会先执行语音、诊断和设置初始化。
+ * 资源用量窗口、右侧栏独立子窗口、截图浮层 / 贴图与主应用共用同一个受信任
+ * HTML/origin,但从这里开始加载不同的模块图。判断必须发生在任何主应用静态依赖
+ * 之前,否则 ESM 会先执行语音、诊断和设置初始化。
*/
const urlParams = new URLSearchParams(window.location.search);
+const isRecordingPreview = urlParams.get('recordingPreview') === '1';
const isRemoteDesktopViewer = urlParams.get('remoteDesktopViewer') === '1';
const isResourceUsageWindow = urlParams.get('resourceUsageWindow') === '1';
const isSidebarWindow = urlParams.get('sidebarWindow') === '1';
+const isRegionScreenshot = urlParams.get('regionScreenshot') === '1';
+const isRegionScreenshotEditor = urlParams.get('regionScreenshotEditor') === '1';
+const isRegionScreenshotPin = urlParams.get('regionScreenshotPin') === '1';
-void (isRemoteDesktopViewer
+void (isRecordingPreview
+ ? import('./recording-preview-entry')
+ : isRemoteDesktopViewer
? import('./remote-desktop-viewer-entry')
: isResourceUsageWindow
? import('./resource-usage-entry')
: isSidebarWindow
? import('./sidebar-window-entry')
- : import('./main-entry')
+ : isRegionScreenshot
+ ? import('./region-screenshot-entry')
+ : isRegionScreenshotEditor
+ ? import('./region-screenshot-entry')
+ : isRegionScreenshotPin
+ ? import('./region-screenshot-pin-entry')
+ : import('./main-entry')
).catch((error: unknown) => {
// 入口加载失败发生在 React boundary 之前,仍通过统一 renderer logger 落盘。
window.electronAPI?.logToMain?.(
diff --git a/apps/desktop/src/renderer/lib/appShortcutStore.ts b/apps/desktop/src/renderer/lib/appShortcutStore.ts
index 041a4c3890..d2b81ff1f4 100644
--- a/apps/desktop/src/renderer/lib/appShortcutStore.ts
+++ b/apps/desktop/src/renderer/lib/appShortcutStore.ts
@@ -1,5 +1,6 @@
import {
getEffectiveAppShortcuts,
+ isAppShortcutId,
normalizeAppShortcutOverrides,
type AppShortcutCombo,
type AppShortcutId,
@@ -27,9 +28,14 @@ let platform = 'darwin';
let effective = new Map<AppShortcutId, AppShortcutCombo[]>();
let overridesSnapshot: AppShortcutOverrides = {};
let voiceYieldCombos: AppShortcutCombo[] = [];
+let globalFailures: AppShortcutId[] = [];
const listeners = new Set<() => void>();
let initialized = false;
+function readGlobalFailures(raw: unknown): AppShortcutId[] {
+ return Array.isArray(raw) ? raw.filter(isAppShortcutId) : [];
+}
+
function recomputeEffective(): void {
effective = getEffectiveAppShortcuts(overridesSnapshot, platform, voiceYieldCombos);
}
@@ -54,11 +60,13 @@ function ensureInitialized(): void {
const state = api.getState();
platform = state.platform;
overridesSnapshot = normalizeAppShortcutOverrides(state.overrides, platform);
+ globalFailures = readGlobalFailures(state.globalFailures);
} catch {
overridesSnapshot = {};
}
api.onChanged((payload) => {
overridesSnapshot = normalizeAppShortcutOverrides(payload?.overrides, platform);
+ globalFailures = readGlobalFailures(payload?.globalFailures);
recomputeEffective();
listeners.forEach((cb) => cb());
});
@@ -89,6 +97,12 @@ export function getAppShortcutOverrides(): AppShortcutOverrides {
return { ...overridesSnapshot };
}
+/** 当前生效组合未能注册到系统 (多为被其它应用占用) 的全局快捷键。 */
+export function getAppShortcutGlobalFailures(): AppShortcutId[] {
+ ensureInitialized();
+ return [...globalFailures];
+}
+
export function getAppShortcutPlatform(): string {
ensureInitialized();
return platform;
diff --git a/apps/desktop/src/renderer/lib/composerActionsBus.ts b/apps/desktop/src/renderer/lib/composerActionsBus.ts
index c71aea7d77..2364bab22b 100644
--- a/apps/desktop/src/renderer/lib/composerActionsBus.ts
+++ b/apps/desktop/src/renderer/lib/composerActionsBus.ts
@@ -4,6 +4,8 @@
* other's insert requests.
*/
+import { getDataOwnerGeneration, isDataOwnerGenerationCurrent, type DataOwnerGeneration } from '@/contexts/dataOwnerGeneration';
+
const INSERT_SESSION_LINK_EVENT = 'cindy-composer-insert-session-link';
/** A request to insert one conversation/message deep link into a composer. */
@@ -120,3 +122,66 @@ export function insertPromptIntoEditor(
if (!opts.isEmpty) chain.splitBlock();
chain.insertContent(opts.text).run();
}
+
+/**
+ * 一次性「发送这份草稿」请求。用户在别处点了一个明确的一键动作 (如截图工具条的
+ * 「翻译」), 入口先把草稿写进 composerDraftStore, 再请求该草稿所在的输入框按
+ * 普通发送键同一条路径发出 —— 不绕过模型、权限、建任务等任何发送逻辑。
+ *
+ * 请求带上期望出现的附件, 输入框等草稿与附件都同步到位才发, 每条请求只发一次;
+ * 暂时没有输入框接住 (还在路由切换) 时保留到过期, 之后挂载的输入框再取。
+ */
+export interface ComposerSubmitRequest {
+ storageKey: string;
+ /** 草稿里必须已有这张附件 (按 url 比对) 才发送。 */
+ attachmentUrl: string;
+ expiresAt: number;
+}
+
+const DEFAULT_SUBMIT_TTL_MS = 15_000;
+const pendingSubmitRequests = new Map<string, ComposerSubmitRequest & { owner: DataOwnerGeneration }>();
+const submitRequestHandlers = new Map<string, Set<() => void>>();
+
+export function requestComposerSubmit(
+ request: Omit<ComposerSubmitRequest, 'expiresAt'>,
+ ttlMs = DEFAULT_SUBMIT_TTL_MS,
+): void {
+ pendingSubmitRequests.set(request.storageKey, { ...request, expiresAt: Date.now() + ttlMs, owner: getDataOwnerGeneration() });
+ for (const handler of submitRequestHandlers.get(request.storageKey) ?? []) handler();
+}
+
+/** 当前仍有效的请求 (不取走)。 */
+export function peekComposerSubmitRequest(storageKey: string): ComposerSubmitRequest | null {
+ const request = pendingSubmitRequests.get(storageKey);
+ if (!request) return null;
+ if (request.expiresAt <= Date.now() || !isDataOwnerGenerationCurrent(request.owner)) {
+ pendingSubmitRequests.delete(storageKey);
+ return null;
+ }
+ return request;
+}
+
+/** 取走请求; 之后同一请求不会再触发发送。 */
+export function takeComposerSubmitRequest(storageKey: string): ComposerSubmitRequest | null {
+ const request = peekComposerSubmitRequest(storageKey);
+ pendingSubmitRequests.delete(storageKey);
+ return request;
+}
+
+/** 订阅某个草稿的发送请求; 订阅时已有待处理请求会立即通知一次。 */
+export function subscribeComposerSubmitRequest(
+ storageKey: string,
+ handler: () => void,
+): () => void {
+ let handlers = submitRequestHandlers.get(storageKey);
+ if (!handlers) {
+ handlers = new Set();
+ submitRequestHandlers.set(storageKey, handlers);
+ }
+ handlers.add(handler);
+ if (peekComposerSubmitRequest(storageKey)) queueMicrotask(handler);
+ return () => {
+ handlers.delete(handler);
+ if (handlers.size === 0) submitRequestHandlers.delete(storageKey);
+ };
+}
diff --git a/apps/desktop/src/renderer/lib/composerDraftStore.ts b/apps/desktop/src/renderer/lib/composerDraftStore.ts
index 6c3bad962a..a6a447ccbd 100644
--- a/apps/desktop/src/renderer/lib/composerDraftStore.ts
+++ b/apps/desktop/src/renderer/lib/composerDraftStore.ts
@@ -344,8 +344,7 @@ export function subscribeDraftContent(sessionId: string, handler: DraftListener)
};
}
-function recomputeDraftPresence(sessionId: string): void {
- const key = draftKey(sessionId);
+function recomputeDraftPresence(sessionId: string, key = draftKey(sessionId)): void {
const contentSet = contentListeners.get(key);
if (contentSet)
for (const fn of contentSet) {
@@ -442,7 +441,27 @@ export function saveDraft(
draft: ComposerDraft,
opts?: { silent?: boolean; preserveRemoteOptimisticRecovery?: boolean },
): void {
- const key = draftKey(sessionId);
+ saveDraftAtKey(sessionId, draftKey(sessionId), draft, opts);
+}
+
+/** Pin deferred recovery to the originating owner's namespace, even after switching accounts. */
+export function captureDraftRecoveryScope(sessionId: string) {
+ const token = captureDraftDiscardToken(sessionId);
+ return {
+ get: () => drafts.get(token.ownerScopedKey),
+ save: (draft: ComposerDraft) => {
+ if (!isDraftDiscardTokenCurrent(token)) return;
+ saveDraftAtKey(sessionId, token.ownerScopedKey, draft, {
+ silent: token.ownerScopedKey !== draftKey(sessionId),
+ });
+ },
+ };
+}
+
+function saveDraftAtKey(
+ sessionId: string, key: string, draft: ComposerDraft,
+ opts?: { silent?: boolean; preserveRemoteOptimisticRecovery?: boolean },
+): void {
if (!opts?.silent && !opts?.preserveRemoteOptimisticRecovery) {
remoteOptimisticRecoveries.delete(key);
}
@@ -480,7 +499,7 @@ export function saveDraft(
}
// Presence notify is independent of `silent` — the sidebar must learn about
// keystroke saves (which are silent) too.
- recomputeDraftPresence(sessionId);
+ recomputeDraftPresence(sessionId, key);
syncDraftUrlsToMain();
}
diff --git a/apps/desktop/src/renderer/recording-preview-entry.tsx b/apps/desktop/src/renderer/recording-preview-entry.tsx
new file mode 100644
index 0000000000..38031252b1
--- /dev/null
+++ b/apps/desktop/src/renderer/recording-preview-entry.tsx
@@ -0,0 +1,31 @@
+import { useEffect, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import '@fontsource-variable/inter';
+import 'harmonyos-sans-sc-webfont-splitted';
+import i18n from '@/i18n';
+import './themes/colors';
+import './styles/globals.css';
+import { RecordingPreview } from './features/region-screenshot/RecordingPreview';
+import { ScreenshotErrorBoundary } from './features/region-screenshot/ScreenshotErrorBoundary';
+import type { RecordingPreviewDocument } from '../shared/regionCapture';
+import { applyFontSettings, getInitialFontSettings } from './hooks/useFontSettings';
+import { getInitialThemeVariant } from './hooks/useTheme';
+import { bootstrapLocalThemesSync } from './themes/local-themes';
+import { themeService } from './themes/theme-service';
+
+document.documentElement.dataset.platform = window.electronAPI.platform;
+bootstrapLocalThemesSync();
+themeService.applyTheme(getInitialThemeVariant().theme);
+applyFontSettings(getInitialFontSettings());
+const bridge = window.recordingPreview!;
+function App() {
+ const [clip, setClip] = useState<RecordingPreviewDocument | null>(null);
+ useEffect(() => {
+ const begin = bridge.onBegin((value) => { void i18n.changeLanguage(value.locale); setClip(value); });
+ const end = bridge.onEnd(() => { (document.activeElement as HTMLElement | null)?.blur(); setClip(null); });
+ bridge.ready();
+ return () => { begin(); end(); };
+ }, []);
+ return clip ? <RecordingPreview key={clip.token} document={clip} bridge={bridge} /> : null;
+}
+createRoot(document.getElementById('root')!).render(<ScreenshotErrorBoundary onFailure={() => bridge.failed()}><App /></ScreenshotErrorBoundary>);
diff --git a/apps/desktop/src/renderer/region-screenshot-entry.tsx b/apps/desktop/src/renderer/region-screenshot-entry.tsx
new file mode 100644
index 0000000000..8de78965ae
--- /dev/null
+++ b/apps/desktop/src/renderer/region-screenshot-entry.tsx
@@ -0,0 +1,51 @@
+import { createRoot } from 'react-dom/client';
+
+import '@fontsource-variable/inter';
+import 'harmonyos-sans-sc-webfont-splitted';
+
+import '@/i18n';
+import './themes/colors';
+import './styles/globals.css';
+
+import { ScreenshotErrorBoundary } from './features/region-screenshot/ScreenshotErrorBoundary';
+import { RegionScreenshotOverlay } from './features/region-screenshot/RegionScreenshotOverlay';
+import type { RegionScreenshotOverlayBridge } from './features/region-screenshot/bridge';
+import { applyFontSettings, getInitialFontSettings } from './hooks/useFontSettings';
+import { getInitialThemeVariant } from './hooks/useTheme';
+import { bootstrapLocalThemesSync } from './themes/local-themes';
+import { themeService } from './themes/theme-service';
+
+/** 全局框选截图浮层入口 (隐藏预热, 每次截图由 main 推送会话)。 */
+document.documentElement.dataset.platform = window.electronAPI.platform;
+// Scrolling leaves the source region transparent while the original overlay
+// owns only its outline, thumbnail and actions.
+const imageEditor = !!window.regionScreenshotEditor;
+if (!imageEditor) {
+ document.documentElement.style.background = 'transparent';
+ document.body.style.background = 'transparent';
+}
+bootstrapLocalThemesSync();
+themeService.applyTheme(getInitialThemeVariant().theme);
+applyFontSettings(getInitialFontSettings());
+
+const rootElement = document.getElementById('root');
+let editorToken: string | null = null;
+const editor = window.regionScreenshotEditor;
+const bridge: RegionScreenshotOverlayBridge | undefined = editor ? {
+ ...editor,
+ onBegin: (callback) => editor.onBegin((payload) => { editorToken = payload.token; callback(payload); }),
+ onEnd: (callback) => editor.onEnd(() => { editorToken = null; callback(); }),
+ abandon: () => { if (editorToken) editor.cancel(editorToken); },
+ // Rendering adapters only: none of these unused capture capabilities cross preload.
+ onClear: () => () => {}, focused: () => {}, selectionStarted: () => {}, copyText: () => {},
+ elementsAt: async () => [], autoScroll: async () => false, restoreEditor: async () => false,
+ holdCapture: async () => {}, startLive: async () => null, liveFrame: async () => null, saveRecording: async () => false,
+ recordingControls: async () => null, previewRecording: async () => false,
+} : window.regionScreenshot;
+if (!rootElement || !bridge) throw new Error('Missing region screenshot root or bridge');
+
+createRoot(rootElement).render(
+ <ScreenshotErrorBoundary onFailure={() => editor ? editor.failed() : bridge.abandon()}>
+ <RegionScreenshotOverlay bridge={bridge} imageEditor={imageEditor} />
+ </ScreenshotErrorBoundary>,
+);
diff --git a/apps/desktop/src/renderer/region-screenshot-pin-entry.tsx b/apps/desktop/src/renderer/region-screenshot-pin-entry.tsx
new file mode 100644
index 0000000000..635eecfcbe
--- /dev/null
+++ b/apps/desktop/src/renderer/region-screenshot-pin-entry.tsx
@@ -0,0 +1,31 @@
+import { createRoot } from 'react-dom/client';
+
+import '@fontsource-variable/inter';
+import 'harmonyos-sans-sc-webfont-splitted';
+
+import '@/i18n';
+import './themes/colors';
+import './styles/globals.css';
+
+import { ScreenshotErrorBoundary } from './features/region-screenshot/ScreenshotErrorBoundary';
+import { PinView } from './features/region-screenshot/PinView';
+import { applyFontSettings, getInitialFontSettings } from './hooks/useFontSettings';
+import { getInitialThemeVariant } from './hooks/useTheme';
+import { bootstrapLocalThemesSync } from './themes/local-themes';
+import { themeService } from './themes/theme-service';
+
+/** 截图贴图窗口入口: 一张贴图一个窗口。 */
+document.documentElement.dataset.platform = window.electronAPI.platform;
+bootstrapLocalThemesSync();
+themeService.applyTheme(getInitialThemeVariant().theme);
+applyFontSettings(getInitialFontSettings());
+
+const rootElement = document.getElementById('root');
+const bridge = window.regionScreenshotPin;
+if (!rootElement || !bridge) throw new Error('Missing pin root or bridge');
+
+createRoot(rootElement).render(
+ <ScreenshotErrorBoundary onFailure={() => bridge.command('close')}>
+ <PinView bridge={bridge} />
+ </ScreenshotErrorBoundary>,
+);
diff --git a/apps/desktop/src/renderer/vite-env.d.ts b/apps/desktop/src/renderer/vite-env.d.ts
index 3c1381b8f7..ff4f531a60 100644
--- a/apps/desktop/src/renderer/vite-env.d.ts
+++ b/apps/desktop/src/renderer/vite-env.d.ts
@@ -1249,6 +1249,8 @@ interface ElectronAPI {
getState: () => {
overrides: import('../shared/appShortcuts').AppShortcutOverrides;
platform: string;
+ /** 运行态: 注册失败 (多为被其它应用占用) 的全局快捷键 id。 */
+ globalFailures?: unknown;
};
setOverride: (
id: import('../shared/appShortcuts').AppShortcutId,
@@ -1262,6 +1264,7 @@ interface ElectronAPI {
onChanged: (
callback: (payload: {
overrides: import('../shared/appShortcuts').AppShortcutOverrides;
+ globalFailures?: unknown;
}) => void,
) => () => void;
};
@@ -3106,6 +3109,12 @@ interface ElectronAPI {
| null
>;
+ /** 全局截图交给新任务: main 唤醒后取走待处理请求 (只有主窗口能取)。 */
+ regionScreenshotCompose?: {
+ onWake: (callback: () => void) => () => void;
+ take: () => Promise<import('../shared/regionScreenshot').RegionScreenshotComposeRequest | null>;
+ };
+
// ── TextLightbox (text-lightbox F4/F5) ──
/**
* Read a text file (≤ MAX_PREVIEW_MB) for the in-app preview overlay. When
diff --git a/apps/desktop/src/shared/__tests__/regionScreenshot.test.ts b/apps/desktop/src/shared/__tests__/regionScreenshot.test.ts
new file mode 100644
index 0000000000..54eaf94875
--- /dev/null
+++ b/apps/desktop/src/shared/__tests__/regionScreenshot.test.ts
@@ -0,0 +1,393 @@
+import { describe, expect, it } from 'vitest';
+import { ScrollCapture, matchScrollFrames } from '../scrollCapture';
+import { recordingControlsBounds, scrollCaptureLayout, scrollPreviewBounds, validRecordingBytes } from '../regionCapture';
+import type { RegionScreenshotBitmap } from '../regionScreenshot';
+
+import {
+ normalizeRegionSelection,
+ nudgeRegion,
+ regionChromeArea,
+ regionSelectionToImageCrop,
+ resizeRegion,
+ snapCandidates,
+ validateRegionBitmap,
+} from '../regionScreenshot';
+
+// Phase 5/6 contract (unit): the production stitcher must not duplicate fixed chrome,
+// accept uncertain overlap, or exceed its memory budget. Previous geometry tests never
+// supplied successive frames. Minimal input: two 64x96 crops with a 24-row scroll.
+function scrollingFrame(offset: number, header = 0, footer = 0): RegionScreenshotBitmap {
+ const width = 64, height = 96;
+ const data = new Uint8Array(width * height * 4);
+ for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
+ const row = y < header || y >= height - footer ? y : y + offset;
+ let seed = ((row + 1) * 2654435761 + x * 2246822519) >>> 0;
+ seed ^= seed >>> 13;
+ const i = (y * width + x) * 4;
+ data[i] = seed & 255; data[i + 1] = (seed >>> 8) & 255; data[i + 2] = (seed >>> 16) & 255; data[i + 3] = 255;
+ }
+ return { width, height, data };
+}
+
+describe('continuous region capture', () => {
+ // Preview must copy only visible rows, including across stitched parts; full
+ // export must remain identical after scrolling both ways. tier: unit.
+ it('reads bounded preview rows across appended and prepended seams without changing export', () => {
+ const capture = new ScrollCapture(scrollingFrame(24, 8, 8));
+ capture.add(scrollingFrame(0, 8, 8));
+ capture.add(scrollingFrame(48, 8, 8));
+ const full = capture.image();
+ for (const start of [0, 15, 75, 130]) {
+ const image = capture.image(start, 20);
+ expect(image.height).toBe(Math.min(20, full.height - start));
+ expect(image.data).toEqual(full.data.slice(start * 64 * 4, (start + 20) * 64 * 4));
+ }
+ expect(capture.image()).toEqual(full);
+ });
+
+ // User report: preview started at the top instead of the selection bottom.
+ // Cover right-first placement, left fallback and viewport clipping. tier: unit.
+ it('anchors the side preview to the selection bottom and grows upwards', () => {
+ for (const selection of [{ x: 300, y: 200, width: 600, height: 600 }, { x: 1400, y: 20, width: 500, height: 950 }]) {
+ const layout = scrollCaptureLayout(selection, { width: 1920, height: 1080 })!;
+ expect(layout.preview.y + layout.preview.height).toBe(selection.y + selection.height);
+ expect(layout.preview.y).toBeGreaterThanOrEqual(8);
+ for (const height of [80, 400, 2000]) {
+ const bounds = scrollPreviewBounds(layout, height);
+ expect(bounds.y + bounds.height).toBe(selection.y + selection.height);
+ expect(bounds.height).toBe(Math.min(height, layout.preview.height));
+ }
+ }
+ const layout = scrollCaptureLayout({ x: 900, y: 200, width: 600, height: 600 }, { width: 1920, height: 1080 })!;
+ expect(layout.preview.x).toBeGreaterThanOrEqual(1500);
+ });
+ it('stitches downward motion while keeping fixed header and footer exactly once', () => {
+ const first = scrollingFrame(0, 8, 8);
+ const capture = new ScrollCapture(first);
+ expect(capture.add(scrollingFrame(24, 8, 8))).toBe('append');
+ expect(capture.add(scrollingFrame(48, 8, 8))).toBe('append');
+ const output = capture.image();
+ expect(output.height).toBe(144);
+ const expected = new Uint8Array(144 * 64 * 4);
+ expected.set(first.data.subarray(0, 88 * 64 * 4));
+ expected.set(scrollingFrame(24, 8, 8).data.subarray(64 * 64 * 4, 88 * 64 * 4), 88 * 64 * 4);
+ expected.set(scrollingFrame(48, 8, 8).data.subarray(64 * 64 * 4), 112 * 64 * 4);
+ expect(output.data).toEqual(expected);
+ const reverse = new ScrollCapture(scrollingFrame(48, 8, 8));
+ expect(reverse.add(scrollingFrame(24, 8, 8))).toBe('prepend');
+ expect(reverse.add(first)).toBe('prepend');
+ expect(reverse.image()).toEqual(output);
+ });
+
+ it('extends upwards and downwards without duplicating revisited content or losing the anchor on a gap', () => {
+ const capture = new ScrollCapture(scrollingFrame(24));
+ expect(capture.add(scrollingFrame(24))).toBe('same');
+ expect(capture.add(scrollingFrame(0))).toBe('prepend');
+ expect(capture.add(scrollingFrame(300))).toBe('unmatched');
+ expect(capture.add(scrollingFrame(48))).toBe('append');
+ expect(capture.height).toBe(144);
+ expect(capture.add(scrollingFrame(24))).toBe('same');
+ expect(capture.height).toBe(144);
+ expect(capture.add(scrollingFrame(72))).toBe('append');
+ expect(capture.height).toBe(168);
+ const forward = new ScrollCapture(scrollingFrame(0));
+ for (const offset of [24, 48, 72]) forward.add(scrollingFrame(offset));
+ expect(capture.image()).toEqual(forward.image());
+ });
+
+ // User report: the overlap warning appears before scrolling. Unit: a blinking
+ // caret or a small hover change must remain stationary, without replacing the
+ // accepted image. Existing tests only used byte-identical stationary frames.
+ it('ignores local repainting at rest and still stitches the next scroll', () => {
+ const first = scrollingFrame(0);
+ const capture = new ScrollCapture(first);
+ for (const width of [2, 20]) {
+ const repaint = { ...first, data: first.data.slice() };
+ for (let y = 40; y < 48; y++) for (let x = 8; x < 8 + width; x++) {
+ repaint.data.fill(255, (y * first.width + x) * 4, (y * first.width + x + 1) * 4);
+ }
+ expect(capture.add(repaint)).toBe('same');
+ expect(capture.image()).toEqual(first);
+ }
+ expect(capture.add(scrollingFrame(24))).toBe('append');
+ expect(capture.height).toBe(120);
+ });
+
+ // Native QA found that whitespace diluted the confidence gap between paragraphs.
+ // Unit: repeated text shapes with a small unique suffix must still stitch at the
+ // exact offset. The dense-noise frames above never exercised this input.
+ it('stitches sparse text-like paragraphs without accumulating blank footer rows', () => {
+ const sparse = (offset: number): RegionScreenshotBitmap => {
+ const width = 240, height = 240, data = new Uint8Array(width * height * 4).fill(255);
+ for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
+ const row = y + offset, block = Math.floor(row / 40);
+ if (row % 40 >= 10 && row % 40 < 18 && ((x < 100 && x % 8 < 3) || (x >= 120 && x < 140 && ((block * 7919) >> (x % 12) & 1)))) {
+ const at = (y * width + x) * 4;
+ data[at] = data[at + 1] = data[at + 2] = 40;
+ }
+ }
+ return { width, height, data };
+ };
+ const capture = new ScrollCapture(sparse(0));
+ for (const offset of [17, 34, 51, 68]) expect(capture.add(sparse(offset))).toBe('append');
+ expect(capture.height).toBe(308);
+ expect(capture.add(sparse(28))).toBe('unmatched');
+ expect(capture.add(sparse(68))).toBe('same');
+ expect(capture.height).toBe(308);
+ });
+
+ // User report: ordinary scrolling stays on the mismatch notice. Unit coverage
+ // previously had no stationary side pane or small capture colour drift.
+ // Minimal production input: 64x96, a fixed left half, a 24-row scroll and +2 RGB.
+ it('matches scrolling content beside a stationary pane with small capture drift', () => {
+ const paneFrame = (offset: number, drift: number) => {
+ const bitmap = scrollingFrame(offset);
+ const fixed = scrollingFrame(0);
+ for (let y = 0; y < bitmap.height; y++) for (let x = 0; x < bitmap.width; x++) {
+ const at = (y * bitmap.width + x) * 4;
+ for (let c = 0; c < 3; c++) bitmap.data[at + c] = Math.min(255, (x < 32 ? fixed.data[at + c] : bitmap.data[at + c]) + drift);
+ }
+ return bitmap;
+ };
+ const capture = new ScrollCapture(paneFrame(0, 0));
+ expect(capture.add(paneFrame(24, 2))).toBe('append');
+ expect(capture.height).toBe(120);
+ expect(capture.add(paneFrame(0, 0))).toBe('same');
+ expect(capture.height).toBe(120);
+ });
+
+ // PR #7300 native reproduction: chat text scrolls over a fixed wallpaper.
+ // The existing stationary-pane test separates background and content by column;
+ // here they share pixels. Unit: two overlapping crops must extend the image,
+ // while revisiting them must not add duplicate rows or alter exported colours.
+ it('stitches text over a stationary wallpaper without duplicating a return scroll', () => {
+ const chat = (offset: number, light: boolean): RegionScreenshotBitmap => {
+ const width = 240, height = 240, data = new Uint8Array(width * height * 4);
+ for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
+ const row = y + offset, line = Math.floor(row / 29);
+ const background = 25 + 35 * (1 + Math.sin(y / 23 + x / 80));
+ const ink = x > 45 && x < 210 && row % 29 < 9 && x % 11 < 5
+ && ((line * 7919 + Math.floor(x / 11) * 3571) >>> (row % 9) & 1);
+ const value = Math.round(ink ? 200 + background * 0.15 : background);
+ const at = (y * width + x) * 4;
+ data[at] = data[at + 1] = data[at + 2] = light ? 255 - value : value;
+ data[at + 3] = 255;
+ }
+ return { width, height, data };
+ };
+ for (const light of [false, true]) {
+ const first = chat(0, light), next = chat(47, light);
+ const capture = new ScrollCapture(first);
+ expect(capture.add(next)).toBe('append');
+ expect(capture.height).toBe(287);
+ const output = capture.image();
+ expect(output.data.slice(-47 * 240 * 4)).toEqual(next.data.slice(-47 * 240 * 4));
+ expect(capture.add(first)).toBe('same');
+ expect(capture.image()).toEqual(output);
+ expect(capture.add(chat(94, light))).toBe('append');
+ expect(capture.height).toBe(334);
+ expect(['same', 'unmatched']).toContain(capture.add(chat(3000, light)));
+ expect(capture.height).toBe(334);
+ }
+ });
+
+ it('rejects ambiguous repeated content and preserves the result at its size limit', () => {
+ const a = scrollingFrame(0), b = scrollingFrame(24);
+ const capture = new ScrollCapture(a, 64 * 100);
+ expect(capture.add(b)).toBe('limit');
+ expect(capture.image()).toEqual(a);
+ const repeated = scrollingFrame(0);
+ for (let y = 0; y < 96; y++) repeated.data.copyWithin(y * 256, (y % 8) * 256, (y % 8 + 1) * 256);
+ const shifted = { ...repeated, data: repeated.data.slice() };
+ for (let y = 0; y < 96; y++) shifted.data.set(repeated.data.subarray(((y + 3) % 8) * 256, ((y + 3) % 8 + 1) * 256), y * 256);
+ expect(matchScrollFrames(repeated, shifted)).toEqual({ kind: 'unmatched' });
+ });
+
+ it('keeps the control panel outside the capture, or refuses an impossible placement', () => {
+ const display = { x: -1920, y: 0, width: 1920, height: 1080 };
+ // Layout uses display-local coordinates on negative-origin monitors too.
+ const selection = { x: 20, y: 20, width: 1200, height: 700 };
+ const panel = recordingControlsBounds(selection, display, false)!;
+ expect(panel).not.toBeNull();
+ expect(panel.y >= selection.y + selection.height || panel.x >= selection.x + selection.width).toBe(true);
+ expect(recordingControlsBounds({ ...display, x: 0, y: 0 }, display, false)).toBeNull();
+ // The former tall panel rejected this region; compact controls fit while annotations do not.
+ const wide = { x: 0, y: 0, width: 1920, height: 980 };
+ expect(recordingControlsBounds(wide, display, false)?.y).toBeGreaterThanOrEqual(980);
+ expect(recordingControlsBounds(wide, display, true)).toBeNull();
+ // The scrolling preview must remain reachable even beside a low selection.
+ const viewport = { width: 1920, height: 1080 };
+ for (const region of [{ x: 300, y: 800, width: 600, height: 200 }, { x: 10, y: 20, width: 1900, height: 700 }]) {
+ const layout = scrollCaptureLayout(region, viewport)!;
+ expect(layout.auto.x + layout.auto.width).toBeLessThanOrEqual(layout.actions.x);
+ for (const rect of [layout.preview, layout.auto, layout.actions]) {
+ expect(rect.x).toBeGreaterThanOrEqual(0);
+ expect(rect.y).toBeGreaterThanOrEqual(0);
+ expect(rect.x + rect.width).toBeLessThanOrEqual(viewport.width);
+ expect(rect.y + rect.height).toBeLessThanOrEqual(viewport.height);
+ expect(rect.x >= region.x + region.width || rect.x + rect.width <= region.x || rect.y >= region.y + region.height || rect.y + rect.height <= region.y).toBe(true);
+ }
+ }
+ });
+
+ // User report (macOS): screenshot chrome sat under the camera housing and over the Dock;
+ // live layouts only knew the display size. Minimal input: a 1470x956 notched display with
+ // a 33pt menu bar, 32pt notch and 70pt Dock. tier: unit.
+ it('keeps live controls out of the menu bar, notch and Dock while room remains', () => {
+ const bounds = { x: 0, y: 0, width: 1470, height: 956 };
+ const area = regionChromeArea(bounds, { x: 0, y: 33, width: 1470, height: 853 }, 32);
+ expect(area).toEqual({ x: 0, y: 33, width: 1470, height: 853 });
+ // An auto-hidden menu bar leaves the notch; negative-origin displays stay display-local.
+ expect(regionChromeArea({ ...bounds, x: -1470 }, { ...bounds, x: -1470 }, 32)).toEqual({ x: 0, y: 32, width: 1470, height: 924 });
+ expect(regionChromeArea(bounds, { x: 0, y: 0, width: 100, height: 956 })).toEqual(bounds);
+ const viewport = { width: 1470, height: 956 };
+ const inside = (r: { x: number; y: number; width: number; height: number }) =>
+ r.x >= area.x && r.y >= area.y && r.x + r.width <= area.x + area.width && r.y + r.height <= area.y + area.height;
+ const nearTop = { x: 200, y: 40, width: 700, height: 500 };
+ const layout = scrollCaptureLayout(nearTop, viewport, area)!;
+ for (const rect of [layout.preview, layout.auto, layout.actions]) expect(inside(rect)).toBe(true);
+ // Without the area the controls fit under this selection only by covering the Dock.
+ const nearDock = { x: 200, y: 300, width: 700, height: 530 };
+ expect(inside(recordingControlsBounds(nearDock, viewport, false)!)).toBe(false);
+ expect(inside(recordingControlsBounds(nearDock, viewport, false, undefined, area)!)).toBe(true);
+ // A selection filling the chrome area still gets controls on the display.
+ const filling = { x: 0, y: 33, width: 1470, height: 800 };
+ expect(recordingControlsBounds(filling, viewport, false, undefined, area)!.y).toBeGreaterThanOrEqual(833);
+ });
+
+ it('rejects mismatched recording formats and unbounded export buffers', () => {
+ const gif = new Uint8Array(20);
+ gif.set(new TextEncoder().encode('GIF89a')); gif[19] = 0x3b;
+ expect(validRecordingBytes(gif, 'gif')).toBe(true);
+ expect(validRecordingBytes(gif, 'webm')).toBe(false);
+ expect(validRecordingBytes(Array.from(gif), 'gif')).toBe(false);
+ gif[19] = 0;
+ expect(validRecordingBytes(gif, 'gif')).toBe(false);
+ });
+});
+
+/**
+ * 框选截图的坐标与 payload 契约: 浮层上报 DIP 选区与最终像素, main 校验后写剪贴板 /
+ * 保存 / 贴图。原图来自 desktopCapturer 缩略图, 多屏共用一个尺寸上限, 混合 DPI 时较小
+ * 的屏会被放大; 裁剪若按 bounds × scaleFactor 计算会截错位置, 不缩回则是放大后的模糊图。
+ */
+describe('region screenshot geometry', () => {
+ it('maps DIP selections onto the frozen image and keeps physical output size', () => {
+ // 1x 屏的缩略图被 4K 副屏的尺寸上限放大到 2 倍
+ expect(
+ regionSelectionToImageCrop(
+ { x: 100, y: 50, width: 200, height: 100 },
+ { width: 1280, height: 720 },
+ { width: 2560, height: 1440 },
+ 1,
+ ),
+ ).toEqual({
+ crop: { x: 200, y: 100, width: 400, height: 200 },
+ output: { width: 200, height: 100 },
+ });
+ // Retina 屏缩略图即物理分辨率: 原样输出, 不缩放
+ expect(
+ regionSelectionToImageCrop(
+ { x: 10, y: 10, width: 300, height: 200 },
+ { width: 1440, height: 900 },
+ { width: 2880, height: 1800 },
+ 2,
+ ),
+ ).toEqual({
+ crop: { x: 20, y: 20, width: 600, height: 400 },
+ output: { width: 600, height: 400 },
+ });
+ });
+
+ it('normalizes reverse drags, clamps to the display, and rejects bad payloads', () => {
+ const viewport = { width: 1280, height: 720 };
+ expect(
+ normalizeRegionSelection({ x: 1300, y: 700, width: -400, height: -100.4 }, viewport),
+ ).toEqual({ x: 900, y: 600, width: 380, height: 100 });
+ expect(normalizeRegionSelection({ x: 0, y: 0, width: Number.NaN, height: 10 }, viewport)).toBeNull();
+ expect(normalizeRegionSelection({ x: 1290, y: 10, width: 50, height: 50 }, viewport)).toBeNull();
+ expect(normalizeRegionSelection('10,10,20,20', viewport)).toBeNull();
+ });
+
+ // 150% 缩放下 1 DIP = 1.5 物理像素: 选区必须落在物理像素网格上, 键盘微调 1 个物理像素
+ // (1/1.5 DIP) 才不会被取整吞掉, 裁剪也不会多 / 少一列像素。
+ it('aligns selections to the physical pixel grid on fractional scale factors', () => {
+ const viewport = { width: 1707, height: 960 };
+ const selection = normalizeRegionSelection(
+ { x: 10.3, y: 20.1, width: 100.2, height: 50 },
+ viewport,
+ 1.5,
+ );
+ expect(selection).not.toBeNull();
+ for (const value of Object.values(selection!)) {
+ expect(Math.abs(value * 1.5 - Math.round(value * 1.5))).toBeLessThan(1e-9);
+ }
+ // 不足一个物理像素的选区视为空
+ expect(normalizeRegionSelection({ x: 5, y: 5, width: 0.2, height: 10 }, viewport, 2)).toBeNull();
+ });
+
+ it('resizes through the opposite edge, keeps corner squares inside the display, and nudges', () => {
+ const viewport = { width: 800, height: 600 };
+ const start = { x: 100, y: 100, width: 200, height: 100 };
+ // 左边手柄拖过右边: 翻转而不是出现负宽度
+ expect(resizeRegion(start, 'w', { x: 350, y: 0 }, viewport)).toEqual({
+ x: 300,
+ y: 100,
+ width: 50,
+ height: 100,
+ });
+ // Shift + 角手柄: 以对角为锚点的正方形, 被屏幕边缘截住时整体缩小
+ expect(resizeRegion(start, 'se', { x: 900, y: 150 }, viewport, true)).toEqual({
+ x: 100,
+ y: 100,
+ width: 500,
+ height: 500,
+ });
+ // Alt + 方向键缩小时至少保留一步, 平移不越出屏幕
+ expect(nudgeRegion(start, 'ArrowLeft', 300, viewport, true).width).toBe(300);
+ expect(nudgeRegion({ ...start, x: 795 }, 'ArrowRight', 10, viewport).x).toBe(600);
+ });
+
+ // 滚轮在候选里逐级切换: 顺序必须由内到外、末尾是整块屏, 重复或越级变小的项会让滚轮「卡住」或跳回内层。
+ it('orders snap candidates from the innermost element out to the whole display', () => {
+ const viewport = { width: 1000, height: 800 };
+ const window = { id: 3, rect: { x: 100, y: 100, width: 600, height: 500 } };
+ const candidates = snapCandidates(
+ { x: 150, y: 150 },
+ window,
+ [
+ { x: 140, y: 140, width: 40, height: 20 },
+ { x: 140, y: 140, width: 40, height: 20 },
+ { x: 120, y: 120, width: 300, height: 200 },
+ // 识别程序偶发的异常外层: 比内层还小, 跳过
+ { x: 145, y: 145, width: 10, height: 10 },
+ // 不包含指针的区域不可能被选中
+ { x: 500, y: 500, width: 50, height: 50 },
+ ],
+ viewport,
+ );
+ expect(candidates).toEqual([
+ { x: 140, y: 140, width: 40, height: 20 },
+ { x: 120, y: 120, width: 300, height: 200 },
+ window.rect,
+ { x: 0, y: 0, width: 1000, height: 800 },
+ ]);
+ });
+});
+
+/**
+ * 页面导出的最终像素直接进 nativeImage.createFromBitmap; 尺寸与字节数对不上会得到错乱
+ * 图像, 超出显示器的尺寸是异常 payload (electron-security: IPC 入参在 main 侧重新校验)。
+ */
+describe('region screenshot export payload', () => {
+ const limit = { width: 100, height: 50 };
+ it.each([
+ ['accepts an exact BGRA buffer', { width: 2, height: 3, data: new Uint8Array(24) }, true],
+ ['rejects a short buffer', { width: 2, height: 3, data: new Uint8Array(23) }, false],
+ ['rejects sizes beyond the display', { width: 101, height: 1, data: new Uint8Array(404) }, false],
+ ['rejects fractional sizes', { width: 1.5, height: 2, data: new Uint8Array(12) }, false],
+ ['rejects plain arrays', { width: 1, height: 1, data: [0, 0, 0, 0] }, false],
+ ])('%s', (_name, payload, accepted) => {
+ expect(validateRegionBitmap(payload, limit) !== null).toBe(accepted);
+ });
+});
diff --git a/apps/desktop/src/shared/appShortcuts.ts b/apps/desktop/src/shared/appShortcuts.ts
index a1d04e8b88..a4e22bcc8e 100644
--- a/apps/desktop/src/shared/appShortcuts.ts
+++ b/apps/desktop/src/shared/appShortcuts.ts
@@ -28,9 +28,11 @@ export interface AppShortcutCombo {
/**
* 冲突检测域: app 与一切重叠; workdir-doc 与 browser / composer 也重叠, 因为
* 文件预览可同屏挂载右侧浏览器和 chat rail, 且在 window capture 阶段消费快捷键。
+ * global = 系统级全局快捷键 (main 用 globalShortcut 注册, Cindy 不在前台也生效),
+ * Cindy 在前台时同样先于应用内监听截走按键, 因此与一切重叠。
* 仅用于改绑冲突判定, 不做展示分组。
*/
-export type AppShortcutScope = 'app' | 'workdir-doc' | 'browser' | 'composer';
+export type AppShortcutScope = 'app' | 'workdir-doc' | 'browser' | 'composer' | 'global';
export const APP_SHORTCUT_IDS = [
'toggle-sidebar',
@@ -51,6 +53,7 @@ export const APP_SHORTCUT_IDS = [
'browser-forward',
'browser-reload',
'cycle-permission-mode',
+ 'region-screenshot',
'switch-session-1',
'switch-session-2',
'switch-session-3',
@@ -157,6 +160,23 @@ export const APP_SHORTCUT_DEFINITIONS: ReadonlyArray<AppShortcutDefinition> = [
rebindable: true,
getDefaultCombos: (platform) => [modCombo('KeyB', platform)],
},
+ // 全局框选截图: Cindy 不在前台也生效,可复制、保存、贴图或交给新任务。默认键避开系统截图
+ // (macOS ⇧⌘3/4/5/6、Windows Win+Shift+S) 与常见 IM 截图键 (Windows: Ctrl+Alt+A、
+ // Alt+A、Ctrl+Shift+A; macOS: 飞书 ⇧⌘A、微信 / QQ ⌃⌘A)。macOS 不用 ⇧⌘S: 它是几乎所有
+ // 应用的「存储为」, 全局注册会把它从每个应用里拿走。暂不支持 Linux (Wayland 无可靠的
+ // 全局快捷键与静默截屏)。
+ {
+ id: 'region-screenshot',
+ scope: 'global',
+ labelKey: 'settings.shortcuts.items.region-screenshot.label',
+ descriptionKey: 'settings.shortcuts.items.region-screenshot.description',
+ rebindable: true,
+ platforms: ['darwin', 'win32'],
+ getDefaultCombos: (platform) =>
+ platform === 'darwin'
+ ? [combo('KeyA', { ctrl: true, shift: true })]
+ : [combo('KeyA', { alt: true, shift: true })],
+ },
{
id: 'cycle-permission-mode',
scope: 'composer',
@@ -734,6 +754,27 @@ export function isAppShortcutComboBindable(comboValue: AppShortcutCombo): boolea
return /^F([1-9]|1[0-9]|2[0-4])$/.test(comboValue.code);
}
+/** 单修饰 (mac ⌘ / 其它 Ctrl) + 这些键是所有应用的编辑惯例键, 全局占用会让别的应用失灵。 */
+const GLOBAL_EDITING_CODES = new Set(['KeyA', 'KeyC', 'KeyV', 'KeyX', 'KeyY', 'KeyZ']);
+
+/**
+ * global scope 条目的额外约束: 必须能表达为 Electron accelerator (globalShortcut
+ * 只认 accelerator, 表达不了 = 绑定了也永远不触发), 且不得占用编辑惯例键 ——
+ * 全局快捷键会在所有应用里截走按键。系统保留键另由 keyboardReserved 判定。
+ */
+export function isGlobalAppShortcutComboUsable(
+ comboValue: AppShortcutCombo,
+ platform: string,
+): boolean {
+ if (comboToElectronAccelerator(comboValue, platform) === null) return false;
+ const editingModifier = platform === 'darwin' ? comboValue.meta : comboValue.ctrl;
+ const otherModifiers =
+ platform === 'darwin'
+ ? comboValue.ctrl || comboValue.alt || comboValue.shift
+ : comboValue.meta || comboValue.alt || comboValue.shift;
+ return !(editingModifier && !otherModifiers && GLOBAL_EDITING_CODES.has(comboValue.code));
+}
+
export function appShortcutCombosEqual(a: AppShortcutCombo, b: AppShortcutCombo): boolean {
return (
a.code === b.code &&
@@ -746,9 +787,9 @@ export function appShortcutCombosEqual(a: AppShortcutCombo, b: AppShortcutCombo)
const OVERLAPPING_SCOPE_PAIRS = new Set(['browser:workdir-doc', 'composer:workdir-doc']);
-/** 冲突检测域判定: app 与一切重叠; workdir-doc 与 browser / composer 同屏重叠。 */
+/** 冲突检测域判定: app / global 与一切重叠; workdir-doc 与 browser / composer 同屏重叠。 */
export function appShortcutScopesOverlap(a: AppShortcutScope, b: AppShortcutScope): boolean {
- if (a === 'app' || b === 'app' || a === b) return true;
+ if (a === 'app' || b === 'app' || a === 'global' || b === 'global' || a === b) return true;
const pair = [a, b].sort().join(':');
return OVERLAPPING_SCOPE_PAIRS.has(pair);
}
diff --git a/apps/desktop/src/shared/regionCapture.ts b/apps/desktop/src/shared/regionCapture.ts
new file mode 100644
index 0000000000..66bc3536c8
--- /dev/null
+++ b/apps/desktop/src/shared/regionCapture.ts
@@ -0,0 +1,131 @@
+import type { RegionPoint, RegionRect, RegionScreenshotBitmap } from './regionScreenshot';
+
+export type RegionCaptureMode = 'scroll' | 'video' | 'gif';
+export interface RegionCaptureBegin {
+ mode: RegionCaptureMode;
+ selection: RegionRect;
+ first: RegionScreenshotBitmap;
+ scrollLayout?: ScrollCaptureLayout;
+ recordingLayout?: { viewport: { width: number; height: number }; controls: RegionRect; area?: RegionRect };
+}
+export interface RecordingPreviewDocument {
+ token: string;
+ locale: string;
+ bytes: Uint8Array<ArrayBuffer>;
+ format: 'webm' | 'gif';
+}
+export const RECORDING_PREVIEW_CHANNEL = {
+ READY: 'recording-preview:ready', BEGIN: 'recording-preview:begin', END: 'recording-preview:end',
+ PAINTED: 'recording-preview:painted', FAILED: 'recording-preview:failed',
+ CLOSE: 'recording-preview:close', MINIMIZE: 'recording-preview:minimize',
+ SAVE: 'recording-preview:save', COPY: 'recording-preview:copy', ACTIVITY: 'recording-preview:activity',
+} as const;
+export interface RegionCaptureFrame {
+ image: RegionScreenshotBitmap;
+ cursor: RegionPoint | null;
+ keys: string[] | null;
+ autoScrolling?: boolean;
+}
+export interface ScrollCaptureLayout {
+ viewport: { width: number; height: number };
+ preview: RegionRect;
+ auto: RegionRect;
+ actions: RegionRect;
+}
+export const REGION_CAPTURE_CHANNEL = {
+ START: 'region-screenshot:live-start',
+ FRAME: 'region-screenshot:live-frame',
+ SAVE: 'region-screenshot:live-save',
+ EDIT: 'region-screenshot:live-edit',
+ HOLD: 'region-screenshot:live-hold',
+ AUTO_SCROLL: 'region-screenshot:auto-scroll',
+ CONTROLS: 'region-screenshot:recording-controls',
+ PREVIEW: 'region-screenshot:recording-preview',
+} as const;
+export const MAX_RECORDING_BYTES = 100 * 1024 * 1024;
+export const MAX_RECORDING_MS = 5 * 60_000;
+
+type Viewport = { width: number; height: number };
+
+const wholeDisplay = (viewport: Viewport): RegionRect => ({ x: 0, y: 0, width: viewport.width, height: viewport.height });
+
+/**
+ * Controls stay on the capture display and outside its pixels, even while dragged.
+ * `area` is the display's chrome area (no menu bar, camera housing or Dock); the
+ * whole display is used only when the selection leaves no room inside it.
+ */
+export function recordingControlsBounds(selection: RegionRect, viewport: Viewport, expanded: boolean, point?: RegionPoint, area: RegionRect = wholeDisplay(viewport)): RegionRect | null {
+ return controlsWithin(selection, area, expanded, point) ?? controlsWithin(selection, wholeDisplay(viewport), expanded, point);
+}
+
+function controlsWithin(selection: RegionRect, area: RegionRect, expanded: boolean, point?: RegionPoint): RegionRect | null {
+ const width = 460, height = expanded ? 336 : 72, gap = 8;
+ const left = area.x + gap, top = area.y + gap, right = area.x + area.width - gap, bottom = area.y + area.height - gap;
+ const selectionRight = selection.x + selection.width, selectionBottom = selection.y + selection.height;
+ const spaces = [
+ { x: left, y: selectionBottom + gap, width: right - left, height: bottom - selectionBottom - gap },
+ { x: left, y: top, width: right - left, height: selection.y - gap - top },
+ { x: selectionRight + gap, y: top, width: right - selectionRight - gap, height: bottom - top },
+ { x: left, y: top, width: selection.x - gap - left, height: bottom - top },
+ ];
+ const candidates = spaces.filter((r) => r.width >= width && r.height >= height).map((r) => ({
+ x: Math.round(Math.max(r.x, Math.min(r.x + r.width - width, point?.x ?? selectionRight - width))),
+ y: Math.round(Math.max(r.y, Math.min(r.y + r.height - height, point?.y ?? (r.y > selection.y ? r.y : selection.y - height - gap)))),
+ width, height,
+ }));
+ if (point) candidates.sort((a, b) => Math.hypot(a.x - point.x, a.y - point.y) - Math.hypot(b.x - point.x, b.y - point.y));
+ return candidates[0] ?? null;
+}
+
+/**
+ * The preview/actions belong to the selection and never cover source pixels.
+ * They prefer the chrome `area` and fall back to the whole display.
+ */
+export function scrollCaptureLayout(selection: RegionRect, viewport: Viewport, area: RegionRect = wholeDisplay(viewport)): ScrollCaptureLayout | null {
+ return scrollLayoutWithin(selection, viewport, area, true) ?? scrollLayoutWithin(selection, viewport, wholeDisplay(viewport), false);
+}
+
+function scrollLayoutWithin(selection: RegionRect, viewport: Viewport, area: RegionRect, preferred: boolean): ScrollCaptureLayout | null {
+ if (area.width < 304) return null;
+ const areaLeft = area.x, areaTop = area.y, areaRight = area.x + area.width, areaBottom = area.y + area.height;
+ const gap = 12, minimumWidth = 208, preferredWidth = Math.min(640, Math.max(400, selection.width * 0.6));
+ const right = selection.x + selection.width;
+ const bottom = selection.y + selection.height;
+ const rightSpace = areaRight - right - gap - 8;
+ const leftSpace = selection.x - areaLeft - gap - 8;
+ const useRight = rightSpace >= minimumWidth;
+ const sideSpace = useRight ? rightSpace : leftSpace;
+ const width = Math.min(preferredWidth, sideSpace >= minimumWidth ? sideSpace : preferredWidth);
+ const sideX = sideSpace >= minimumWidth ? (useRight ? right + gap : selection.x - width - gap) : null;
+ const below = areaBottom - bottom >= 52;
+ const above = selection.y - areaTop >= 52;
+ if (!below && !above) return null;
+ const auto = { x: Math.max(areaLeft, Math.min(areaRight - 132, selection.x + (selection.width - 132) / 2)), y: below ? bottom + 8 : selection.y - 40, width: 132, height: 32 };
+ const actions = { x: Math.max(areaLeft + 152, Math.min(areaRight - 152, right - 144)), y: auto.y, width: 144, height: 32 };
+ auto.x = Math.max(areaLeft + 8, Math.min(auto.x, actions.x - auto.width - gap));
+ if (sideX !== null) {
+ const anchor = Math.min(areaBottom - 8, bottom);
+ // A selection ending inside the menu bar leaves no usable preview in the chrome area.
+ if (preferred && anchor - areaTop - 8 < 48) return null;
+ return { viewport, auto, actions, preview: { x: sideX, y: areaTop + 8, width, height: anchor - areaTop - 8 } };
+ }
+ // Wide selections place the thumbnail above/below, still on this display.
+ const available = below ? areaBottom - bottom - 56 : selection.y - areaTop - 56;
+ const previewHeight = Math.min(220, available);
+ if (previewHeight < 48) return null;
+ const preview = { x: Math.max(areaLeft + 8, Math.min(areaRight - width - 8, right - width)), y: below ? bottom + 48 : selection.y - previewHeight - 48, width, height: previewHeight };
+ return { viewport, auto, actions, preview };
+}
+
+/** Shared by native hit-testing and the bottom-anchored preview. */
+export function scrollPreviewBounds(layout: ScrollCaptureLayout, visibleHeight: number): RegionRect {
+ const height = Math.max(1, Math.min(layout.preview.height, visibleHeight));
+ return { ...layout.preview, y: layout.preview.y + layout.preview.height - height, height };
+}
+
+/** Only fixed-format clip bytes cross the export bridge; paths never do. */
+export function validRecordingBytes(raw: unknown, format: unknown): raw is Uint8Array {
+ if (!(raw instanceof Uint8Array) || raw.length < 16 || raw.length > MAX_RECORDING_BYTES) return false;
+ if (format === 'gif') return String.fromCharCode(...raw.subarray(0, 6)) === 'GIF89a' && raw[raw.length - 1] === 0x3b;
+ return format === 'webm' && raw[0] === 0x1a && raw[1] === 0x45 && raw[2] === 0xdf && raw[3] === 0xa3;
+}
diff --git a/apps/desktop/src/shared/regionScreenshot.ts b/apps/desktop/src/shared/regionScreenshot.ts
new file mode 100644
index 0000000000..32e04f82a8
--- /dev/null
+++ b/apps/desktop/src/shared/regionScreenshot.ts
@@ -0,0 +1,503 @@
+/**
+ * 全局框选截图: main、框选浮层、贴图窗口与主窗口共用的通道名、payload 形状与纯几何。
+ *
+ * 浮层与贴图窗口加载主窗口同源页面 (各自的轻量入口 + 专用 preload), 只能走下面的
+ * 固定通道。main 按 sender 反查所属显示器 / 贴图, 不信任页面传来的任何显示器、
+ * 窗口或贴图身份; 页面导出的像素也按显示器尺寸重新校验。
+ *
+ * 坐标约定: 浮层内一律是该显示器的 DIP (= 窗口 CSS 像素), 定格原图与导出图是物理像素。
+ */
+
+export const REGION_SCREENSHOT_CHANNEL = {
+ /** send: 浮层页面已挂载, 可以接收截图会话 (窗口隐藏预热时发一次)。 */
+ SHELL_READY: 'region-screenshot:shell-ready',
+ /** main → 浮层: 开始一次截图会话 ({@link RegionScreenshotBegin})。 */
+ BEGIN: 'region-screenshot:begin',
+ /** send(token): 定格画面已绘制, 可以显示窗口 (避免先闪一帧底色)。 */
+ PAINTED: 'region-screenshot:painted',
+ /** send(token): 浮层已拿到键盘焦点;全局 Esc 仍保留到截图结束。 */
+ FOCUSED: 'region-screenshot:focused',
+ /** send(token): 用户在本显示器开始框选, main 通知其它显示器清除选区。 */
+ SELECTION_START: 'region-screenshot:selection-start',
+ /** main → 浮层: 清除本显示器的选区。 */
+ CLEAR: 'region-screenshot:clear',
+ /** main → 浮层: 会话结束, 清空画面与全部交互态后隐藏。 */
+ END: 'region-screenshot:end',
+ /** invoke(token, windowId, x, y): 指针下的界面元素, 由内到外 (DIP)。 */
+ ELEMENTS_AT: 'region-screenshot:elements-at',
+ /** send(token, text): 复制取到的颜色值。 */
+ COPY_TEXT: 'region-screenshot:copy-text',
+ /** invoke(token, {@link RegionScreenshotExport}): 用最终图执行动作并结束会话。 */
+ EXPORT: 'region-screenshot:export',
+ /** send(token): 取消本次截图。 */
+ CANCEL: 'region-screenshot:cancel',
+ /**
+ * send: 页面已丢失会话 (重新加载 / 重新挂载) 却仍可能显示着, 请 main 结束本浮层所在的
+ * 会话。不带 token —— 页面此时已没有 token; main 只按 sender 判断它是否属于当前会话。
+ */
+ ABANDON: 'region-screenshot:abandon',
+} as const;
+
+/** Local-only image editor. Every incoming signal is bound to its top-level renderer. */
+export const REGION_SCREENSHOT_EDITOR_CHANNEL = {
+ READY: 'region-screenshot-editor:ready',
+ BEGIN: 'region-screenshot-editor:begin',
+ END: 'region-screenshot-editor:end',
+ PAINTED: 'region-screenshot-editor:painted',
+ CANCEL: 'region-screenshot-editor:cancel',
+ MINIMIZE: 'region-screenshot-editor:minimize',
+ EXPORT: 'region-screenshot-editor:export',
+ ACTIVITY: 'region-screenshot-editor:activity',
+ FAILED: 'region-screenshot-editor:failed',
+} as const;
+
+export const REGION_SCREENSHOT_PIN_CHANNEL = {
+ /** send: 贴图页面已挂载。 */
+ SHELL_READY: 'region-screenshot-pin:shell-ready',
+ /** main → 贴图: 要显示的图 ({@link RegionScreenshotPinInit})。 */
+ INIT: 'region-screenshot-pin:init',
+ /** send: 图已绘制, 可以显示窗口。 */
+ PAINTED: 'region-screenshot-pin:painted',
+ /** send: 开始一次拖动 (main 记下当前位置与指针)。 */
+ DRAG_START: 'region-screenshot-pin:drag-start',
+ /** send: 拖动中 (main 按指针的屏幕位移移动窗口)。 */
+ DRAG_MOVE: 'region-screenshot-pin:drag-move',
+ /** send(steps, x, y): 滚轮缩放, 以窗口内 (x, y) 为锚点。 */
+ ZOOM: 'region-screenshot-pin:zoom',
+ /** send(steps): Ctrl / ⌘ + 滚轮调整不透明度。 */
+ OPACITY: 'region-screenshot-pin:opacity',
+ /** send: 弹出贴图菜单。 */
+ MENU: 'region-screenshot-pin:menu',
+ /** send(command): 键盘快捷操作 ({@link RegionScreenshotPinCommand})。 */
+ COMMAND: 'region-screenshot-pin:command',
+ /** send(hovering): 穿透模式下指针是否停在「恢复」按钮上 (停留时暂时接收点击)。 */
+ UNLOCK_HOVER: 'region-screenshot-pin:unlock-hover',
+ /** main → 贴图: 状态变化 ({@link RegionScreenshotPinState})。 */
+ STATE: 'region-screenshot-pin:state',
+} as const;
+
+/** 截图交给主窗口的任务入口: main 只负责入仓与唤醒, 草稿由主窗口写入。 */
+export const REGION_SCREENSHOT_COMPOSE_CHANNEL = {
+ /** main → 主窗口: 有待处理的截图 (只是唤醒, 内容用 TAKE 取)。 */
+ WAKE: 'region-screenshot:compose-wake',
+ /** invoke: 主窗口取走待处理的截图请求 (只认主窗口)。 */
+ TAKE: 'region-screenshot:compose-take',
+} as const;
+
+export const REGION_SCREENSHOT_AI_ACTIONS = ['ask', 'translate', 'explain', 'extract'] as const;
+export type RegionScreenshotAiAction = (typeof REGION_SCREENSHOT_AI_ACTIONS)[number];
+export type RegionScreenshotAction = 'copy' | 'save' | 'pin' | RegionScreenshotAiAction;
+
+const ACTIONS: readonly string[] = ['copy', 'save', 'pin', ...REGION_SCREENSHOT_AI_ACTIONS];
+
+export function isRegionScreenshotAction(value: unknown): value is RegionScreenshotAction {
+ return typeof value === 'string' && ACTIONS.includes(value);
+}
+
+export function isRegionScreenshotAiAction(value: unknown): value is RegionScreenshotAiAction {
+ return (
+ typeof value === 'string' && (REGION_SCREENSHOT_AI_ACTIONS as readonly string[]).includes(value)
+ );
+}
+
+export const REGION_SCREENSHOT_PIN_COMMANDS = [
+ 'copy',
+ 'save',
+ 'close',
+ 'ask',
+ 'unlock',
+ 'zoom-reset',
+] as const;
+export type RegionScreenshotPinCommand = (typeof REGION_SCREENSHOT_PIN_COMMANDS)[number];
+
+export interface RegionRect {
+ x: number;
+ y: number;
+ width: number;
+ height: number;
+}
+
+export interface RegionSize {
+ width: number;
+ height: number;
+}
+
+export interface RegionPoint {
+ x: number;
+ y: number;
+}
+
+/** 原始像素, BGRA 字节序 (与 NativeImage.toBitmap / createFromBitmap 一致)。 */
+export interface RegionScreenshotBitmap {
+ width: number;
+ height: number;
+ data: Uint8Array<ArrayBuffer>;
+}
+
+/** 定格时可见的窗口 (本显示器 DIP, 已裁到显示器内), 按 z 序从上到下。 */
+export interface RegionScreenshotWindow {
+ id: number;
+ rect: RegionRect;
+}
+
+export interface RegionScreenshotBegin {
+ /** 本次会话标识; 迟到的回调凭它与新会话区分。 */
+ token: string;
+ locale: string;
+ /** 显示器尺寸 (DIP) = 浮层视口; 不依赖页面此刻读到的窗口尺寸。 */
+ viewport: RegionSize;
+ /** 显示器缩放比例: 选区按物理像素网格对齐, 尺寸按物理像素标注。 */
+ scaleFactor: number;
+ /** 定格原图 (无损), 取色、放大镜、马赛克与最终导出都用它。 */
+ frame: RegionScreenshotBitmap;
+ windows: RegionScreenshotWindow[];
+ /** 本显示器上一次截图的选区, 供「重复上次区域」。 */
+ lastRegion: RegionRect | null;
+ /** 截图时鼠标在本显示器上的位置 (DIP); 不在本屏为 null。浮层据此立即吸附高亮, 不必等鼠标移动。 */
+ cursor: RegionPoint | null;
+ /**
+ * 工具条、放大镜、提示等界面元素可用的区域 (本显示器 DIP): 避开菜单栏、刘海、
+ * Dock / 任务栏。选区本身仍可覆盖整块显示器。见 {@link regionChromeArea}。
+ */
+ safeArea: RegionRect;
+}
+
+export interface RegionScreenshotExport {
+ action: RegionScreenshotAction;
+ /** 最终选区 (DIP), main 记为「上次区域」并据此放置贴图。 */
+ selection: RegionRect;
+ /** 已合成标注的最终图 (物理像素)。 */
+ image: RegionScreenshotBitmap;
+}
+
+export interface RegionScreenshotPinInit {
+ locale: string;
+ image: RegionScreenshotBitmap;
+}
+
+export interface RegionScreenshotPinState {
+ opacity: number;
+ passThrough: boolean;
+ /** 当前缩放 (1 = 原始大小)。 */
+ zoom: number;
+}
+
+/** 截图交给新任务: 已入仓的图片与用户点的动作。 */
+export interface RegionScreenshotComposeRequest {
+ id: string;
+ ownerStamp: import('./dataOwnerPush').DataOwnerPushStamp;
+ action: RegionScreenshotAiAction;
+ url: string;
+ filename: string;
+ bytes: number;
+ width: number;
+ height: number;
+}
+
+export type RegionHandle = 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw';
+
+/** 导出图的边长上限 (物理像素); 超出视为异常 payload。 */
+export const REGION_SCREENSHOT_MAX_SIDE = 32_768;
+
+const isFiniteNumber = (value: unknown): value is number =>
+ typeof value === 'number' && Number.isFinite(value);
+
+const validScale = (scale: number) => (scale > 0 && Number.isFinite(scale) ? scale : 1);
+
+/** 对齐到物理像素网格 (DIP × scale 为整数)。 */
+export function snapToPixelGrid(value: number, scale: number): number {
+ const s = validScale(scale);
+ return Math.round(value * s) / s;
+}
+
+/**
+ * 校验浮层传来的选区 (窗口内 DIP), 裁到视口内并对齐物理像素网格。
+ * 结构非法或裁剪后不足一个物理像素返回 null。
+ */
+export function normalizeRegionSelection(
+ raw: unknown,
+ viewport: RegionSize,
+ scale = 1,
+): RegionRect | null {
+ if (!raw || typeof raw !== 'object') return null;
+ const candidate = raw as Record<string, unknown>;
+ const values = [candidate.x, candidate.y, candidate.width, candidate.height];
+ if (!values.every(isFiniteNumber)) return null;
+ const [x, y, width, height] = values as number[];
+ const s = validScale(scale);
+ const left = Math.max(0, snapToPixelGrid(Math.min(x, x + width), s));
+ const top = Math.max(0, snapToPixelGrid(Math.min(y, y + height), s));
+ const right = Math.min(viewport.width, snapToPixelGrid(Math.max(x, x + width), s));
+ const bottom = Math.min(viewport.height, snapToPixelGrid(Math.max(y, y + height), s));
+ if ((right - left) * s < 1 - 1e-6 || (bottom - top) * s < 1 - 1e-6) return null;
+ return { x: left, y: top, width: right - left, height: bottom - top };
+}
+
+/**
+ * 把 DIP 选区映射到定格原图的像素裁剪区域。
+ *
+ * 原图来自 desktopCapturer 缩略图, 所有显示器共用一个 thumbnailSize 上限, 实际
+ * 尺寸 = 按比例缩放后的显示器画面, 不一定等于 bounds × scaleFactor (混合 DPI 时
+ * 较小的屏可能被放大)。因此按「原图宽 / 显示器 DIP 宽」换算, 并给出该选区的
+ * 物理像素尺寸; 裁出的图比物理尺寸大时由调用方缩回, 避免出现被放大的模糊截图。
+ */
+export function regionSelectionToImageCrop(
+ selection: RegionRect,
+ displaySize: RegionSize,
+ imageSize: RegionSize,
+ scaleFactor: number,
+): { crop: RegionRect; output: RegionSize } | null {
+ if (displaySize.width <= 0 || displaySize.height <= 0) return null;
+ if (imageSize.width <= 0 || imageSize.height <= 0) return null;
+ const sx = imageSize.width / displaySize.width;
+ const sy = imageSize.height / displaySize.height;
+ const left = Math.max(0, Math.round(selection.x * sx));
+ const top = Math.max(0, Math.round(selection.y * sy));
+ const right = Math.min(imageSize.width, Math.round((selection.x + selection.width) * sx));
+ const bottom = Math.min(imageSize.height, Math.round((selection.y + selection.height) * sy));
+ if (right - left < 1 || bottom - top < 1) return null;
+ const crop = { x: left, y: top, width: right - left, height: bottom - top };
+ const scale = validScale(scaleFactor);
+ const physical = {
+ width: Math.max(1, Math.round(selection.width * scale)),
+ height: Math.max(1, Math.round(selection.height * scale)),
+ };
+ const output =
+ crop.width > physical.width || crop.height > physical.height
+ ? physical
+ : { width: crop.width, height: crop.height };
+ return { crop, output };
+}
+
+/**
+ * 校验页面传来的位图: 尺寸为正整数且不超过 `max`, 字节数正好是 BGRA 四通道。
+ * 只接受真正的 Uint8Array (structured clone 之后仍是), 不接受普通数组。
+ */
+export function validateRegionBitmap(
+ raw: unknown,
+ max: RegionSize,
+): RegionScreenshotBitmap | null {
+ if (!raw || typeof raw !== 'object') return null;
+ const { width, height, data } = raw as Record<string, unknown>;
+ if (!Number.isInteger(width) || !Number.isInteger(height)) return null;
+ const w = width as number;
+ const h = height as number;
+ if (w < 1 || h < 1 || w > max.width || h > max.height) return null;
+ if (w > REGION_SCREENSHOT_MAX_SIDE || h > REGION_SCREENSHOT_MAX_SIDE) return null;
+ if (!(data instanceof Uint8Array) || data.byteLength !== w * h * 4) return null;
+ return { width: w, height: h, data: data as Uint8Array<ArrayBuffer> };
+}
+
+const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));
+
+/** 两点张成的矩形; `square` 时以 anchor 为固定角取较长边的正方形 (不越出视口)。 */
+export function rectFromDrag(
+ anchor: RegionPoint,
+ point: RegionPoint,
+ viewport: RegionSize,
+ square = false,
+): RegionRect {
+ let x = clamp(point.x, 0, viewport.width);
+ let y = clamp(point.y, 0, viewport.height);
+ if (square) {
+ const dirX = x >= anchor.x ? 1 : -1;
+ const dirY = y >= anchor.y ? 1 : -1;
+ const room = Math.min(
+ dirX > 0 ? viewport.width - anchor.x : anchor.x,
+ dirY > 0 ? viewport.height - anchor.y : anchor.y,
+ );
+ const side = Math.min(Math.max(Math.abs(x - anchor.x), Math.abs(y - anchor.y)), room);
+ x = anchor.x + dirX * side;
+ y = anchor.y + dirY * side;
+ }
+ return {
+ x: Math.min(anchor.x, x),
+ y: Math.min(anchor.y, y),
+ width: Math.abs(x - anchor.x),
+ height: Math.abs(y - anchor.y),
+ };
+}
+
+/**
+ * 拖动手柄调整选区。`start` 是按下手柄时的选区; 越过对边时翻转, 不会出现负尺寸。
+ * `square` 时角手柄保持正方形, 边手柄不受影响。
+ */
+export function resizeRegion(
+ start: RegionRect,
+ handle: RegionHandle,
+ point: RegionPoint,
+ viewport: RegionSize,
+ square = false,
+): RegionRect {
+ const px = clamp(point.x, 0, viewport.width);
+ const py = clamp(point.y, 0, viewport.height);
+ if (square && handle.length === 2) {
+ const anchor = {
+ x: handle.includes('w') ? start.x + start.width : start.x,
+ y: handle.includes('n') ? start.y + start.height : start.y,
+ };
+ return rectFromDrag(anchor, { x: px, y: py }, viewport, true);
+ }
+ let left = start.x;
+ let top = start.y;
+ let right = start.x + start.width;
+ let bottom = start.y + start.height;
+ if (handle.includes('w')) left = px;
+ if (handle.includes('e')) right = px;
+ if (handle.includes('n')) top = py;
+ if (handle.includes('s')) bottom = py;
+ return {
+ x: Math.min(left, right),
+ y: Math.min(top, bottom),
+ width: Math.abs(right - left),
+ height: Math.abs(bottom - top),
+ };
+}
+
+/** 整体平移选区, 不越出视口。 */
+export function moveRegion(
+ rect: RegionRect,
+ dx: number,
+ dy: number,
+ viewport: RegionSize,
+): RegionRect {
+ return {
+ ...rect,
+ x: clamp(rect.x + dx, 0, Math.max(0, viewport.width - rect.width)),
+ y: clamp(rect.y + dy, 0, Math.max(0, viewport.height - rect.height)),
+ };
+}
+
+export type RegionArrowKey = 'ArrowLeft' | 'ArrowRight' | 'ArrowUp' | 'ArrowDown';
+
+export function isRegionArrowKey(key: string): key is RegionArrowKey {
+ return key === 'ArrowLeft' || key === 'ArrowRight' || key === 'ArrowUp' || key === 'ArrowDown';
+}
+
+/**
+ * 方向键微调: 默认平移; `resize` 时移动右 / 下边 (→ ↓ 放大, ← ↑ 缩小), 至少保留 `step`。
+ */
+export function nudgeRegion(
+ rect: RegionRect,
+ key: RegionArrowKey,
+ step: number,
+ viewport: RegionSize,
+ resize = false,
+): RegionRect {
+ const dx = key === 'ArrowLeft' ? -step : key === 'ArrowRight' ? step : 0;
+ const dy = key === 'ArrowUp' ? -step : key === 'ArrowDown' ? step : 0;
+ if (!resize) return moveRegion(rect, dx, dy, viewport);
+ return {
+ ...rect,
+ width: clamp(rect.width + dx, step, viewport.width - rect.x),
+ height: clamp(rect.height + dy, step, viewport.height - rect.y),
+ };
+}
+
+/** 指针所在的选区手柄 (边线附近 `tolerance` 范围内); 不在手柄上返回 null。 */
+export function regionHandleAt(
+ rect: RegionRect,
+ point: RegionPoint,
+ tolerance: number,
+): RegionHandle | null {
+ const { x, y } = point;
+ const right = rect.x + rect.width;
+ const bottom = rect.y + rect.height;
+ if (x < rect.x - tolerance || x > right + tolerance) return null;
+ if (y < rect.y - tolerance || y > bottom + tolerance) return null;
+ const near = (value: number, edge: number) => Math.abs(value - edge) <= tolerance;
+ const vertical = near(y, rect.y) ? 'n' : near(y, bottom) ? 's' : '';
+ const horizontal = near(x, rect.x) ? 'w' : near(x, right) ? 'e' : '';
+ const handle = `${vertical}${horizontal}`;
+ return handle ? (handle as RegionHandle) : null;
+}
+
+export function rectContains(rect: RegionRect, point: RegionPoint): boolean {
+ return (
+ point.x >= rect.x &&
+ point.x < rect.x + rect.width &&
+ point.y >= rect.y &&
+ point.y < rect.y + rect.height
+ );
+}
+
+/** 界面元素区域小于这个尺寸时视为异常 (如工作区读数错误), 改用整块显示器。 */
+const MIN_CHROME_AREA = 320;
+
+/**
+ * 截图界面元素可用的区域 (显示器内 DIP): 系统工作区 (已除去菜单栏、Dock / 任务栏),
+ * 顶部再让出摄像头刘海 `topInset` (菜单栏自动隐藏时工作区仍包含刘海那一条)。
+ * 全局坐标的 `bounds` / `workArea` 来自 Electron Display; 结果异常时返回整块显示器。
+ */
+export function regionChromeArea(bounds: RegionRect, workArea: RegionRect, topInset = 0): RegionRect {
+ const whole = { x: 0, y: 0, width: bounds.width, height: bounds.height };
+ const values = [bounds.x, bounds.y, bounds.width, bounds.height, workArea.x, workArea.y, workArea.width, workArea.height, topInset];
+ if (!values.every(isFiniteNumber)) return whole;
+ const left = clamp(workArea.x - bounds.x, 0, bounds.width);
+ const right = clamp(workArea.x + workArea.width - bounds.x, 0, bounds.width);
+ const top = clamp(Math.max(workArea.y - bounds.y, topInset), 0, bounds.height);
+ const bottom = clamp(workArea.y + workArea.height - bounds.y, 0, bounds.height);
+ if (right - left < MIN_CHROME_AREA || bottom - top < MIN_CHROME_AREA) return whole;
+ return { x: left, y: top, width: right - left, height: bottom - top };
+}
+
+/** 把 `size` 大小的界面元素移进 `area`; 放不下时贴住左上角。 */
+export function clampIntoArea(point: RegionPoint, size: RegionSize, area: RegionRect): RegionPoint {
+ return {
+ x: Math.max(area.x, Math.min(point.x, area.x + area.width - size.width)),
+ y: Math.max(area.y, Math.min(point.y, area.y + area.height - size.height)),
+ };
+}
+
+/** 与视口求交; 无交集返回 null。 */
+export function intersectRegion(rect: RegionRect, viewport: RegionSize): RegionRect | null {
+ const left = Math.max(0, rect.x);
+ const top = Math.max(0, rect.y);
+ const right = Math.min(viewport.width, rect.x + rect.width);
+ const bottom = Math.min(viewport.height, rect.y + rect.height);
+ if (right - left < 1 || bottom - top < 1) return null;
+ return { x: left, y: top, width: right - left, height: bottom - top };
+}
+
+export function sameRegion(a: RegionRect, b: RegionRect): boolean {
+ return (
+ Math.abs(a.x - b.x) < 0.5 &&
+ Math.abs(a.y - b.y) < 0.5 &&
+ Math.abs(a.width - b.width) < 0.5 &&
+ Math.abs(a.height - b.height) < 0.5
+ );
+}
+
+/** 指针下最上层的窗口 (windows 已按 z 序从上到下)。 */
+export function topWindowAt(
+ windows: readonly RegionScreenshotWindow[],
+ point: RegionPoint,
+): RegionScreenshotWindow | null {
+ return windows.find((window) => rectContains(window.rect, point)) ?? null;
+}
+
+/**
+ * 悬停吸附的候选选区, 由内到外: 指针下的界面元素 → 所在窗口 → 整块显示器。
+ * 只保留包含指针、与视口相交的区域, 相同区域只留一个, 比内层更小的外层视为
+ * 异常并跳过; 滚轮在这串候选里切换层级。
+ */
+export function snapCandidates(
+ point: RegionPoint,
+ window: RegionScreenshotWindow | null,
+ elements: readonly RegionRect[],
+ viewport: RegionSize,
+): RegionRect[] {
+ const result: RegionRect[] = [];
+ const push = (rect: RegionRect) => {
+ const clipped = intersectRegion(rect, viewport);
+ if (!clipped || !rectContains(clipped, point)) return;
+ if (result.some((existing) => sameRegion(existing, clipped))) return;
+ const last = result[result.length - 1];
+ if (last && clipped.width * clipped.height < last.width * last.height) return;
+ result.push(clipped);
+ };
+ for (const rect of elements) push(rect);
+ if (window) push(window.rect);
+ push({ x: 0, y: 0, width: viewport.width, height: viewport.height });
+ return result;
+}
diff --git a/apps/desktop/src/shared/scrollCapture.ts b/apps/desktop/src/shared/scrollCapture.ts
new file mode 100644
index 0000000000..d8889d412a
--- /dev/null
+++ b/apps/desktop/src/shared/scrollCapture.ts
@@ -0,0 +1,209 @@
+import type { RegionScreenshotBitmap } from './regionScreenshot';
+
+export type ScrollMatch =
+ | { kind: 'same' | 'unmatched' }
+ | { kind: 'append' | 'prepend'; offset: number; header: number; footer: number };
+
+const COLUMNS = 24;
+// Copy the exact columns used by matching into contiguous rows once. Searching
+// every offset in a full-resolution bitmap otherwise repeatedly touches distant
+// cache lines (and does the same work again for reverse scrolling).
+function sampleColumns(frame: RegionScreenshotBitmap, contrast = false): RegionScreenshotBitmap {
+ const columns = Array.from({ length: COLUMNS }, (_, column) => Math.floor(frame.width * (0.05 + (column / (COLUMNS - 1)) * 0.9)));
+ const data = new Uint8Array(frame.height * COLUMNS * 4);
+ for (let y = 0; y < frame.height; y++) {
+ for (let column = 0; column < COLUMNS; column++) {
+ const from = (y * frame.width + columns[column]) * 4;
+ const to = (y * COLUMNS + column) * 4;
+ data[to] = frame.data[from];
+ data[to + 1] = frame.data[from + 1];
+ data[to + 2] = frame.data[from + 2];
+ if (contrast) {
+ // A fixed wallpaper can sit underneath moving, translucent text. Remove
+ // the local background in matching features only; exported pixels stay
+ // untouched. Nine horizontal pixels retain glyph detail while suppressing
+ // smooth background gradients. Centre signed contrast in the byte range.
+ for (let channel = 0; channel < 3; channel++) {
+ let background = 0;
+ for (let dx = -4; dx <= 4; dx++) {
+ const x = Math.max(0, Math.min(frame.width - 1, columns[column] + dx));
+ background += frame.data[(y * frame.width + x) * 4 + channel];
+ }
+ data[to + channel] = Math.round(128 + (frame.data[from + channel] - background / 9) / 2);
+ }
+ }
+ }
+ }
+ return { width: COLUMNS, height: frame.height, data };
+}
+
+const errorAt = (a: RegionScreenshotBitmap, b: RegionScreenshotBitmap, ay: number, by: number, columns: readonly number[]) => {
+ let error = 0;
+ const aRow = ay * a.width * 4;
+ const bRow = by * b.width * 4;
+ for (const x of columns) {
+ const ai = aRow + x * 4;
+ const bi = bRow + x * 4;
+ error += Math.abs(a.data[ai] - b.data[bi]);
+ error += Math.abs(a.data[ai + 1] - b.data[bi + 1]);
+ error += Math.abs(a.data[ai + 2] - b.data[bi + 2]);
+ }
+ return error / (columns.length * 3);
+};
+
+/** Find downward scrolling with overlap; ambiguous/repeated content is never appended. */
+export function matchScrollFrames(previous: RegionScreenshotBitmap, next: RegionScreenshotBitmap, allowReverse = true): ScrollMatch {
+ if (previous.width !== next.width || previous.height !== next.height || previous.height < 32) return { kind: 'unmatched' };
+ const colour = matchSampledFrames(sampleColumns(previous), sampleColumns(next), allowReverse);
+ if (colour.kind !== 'unmatched') return colour;
+ // Retry rejected colour matches using local contrast, with the same independent
+ // columns, overlap, ambiguity and full-row checks. Do not relax the confidence
+ // thresholds or replace the anchor with an unverified frame after a mismatch.
+ const detail = matchSampledFrames(sampleColumns(previous, true), sampleColumns(next, true), allowReverse);
+ return detail.kind === 'append' || detail.kind === 'prepend' ? detail : colour;
+}
+
+function matchSampledFrames(previous: RegionScreenshotBitmap, next: RegionScreenshotBitmap, allowReverse: boolean): ScrollMatch {
+ const height = previous.height;
+ // Stationary side panes and margins do not vote against content that moved.
+ // Require several independent columns so a blinking caret cannot become a scroll.
+ const allColumns = Array.from({ length: COLUMNS }, (_, column) => column);
+ const columns = allColumns.filter((x) => {
+ let error = 0;
+ for (let y = 0; y < height; y++) error += errorAt(previous, next, y, y, [x]);
+ return error / height > 3;
+ });
+ // A caret/hover repaint is not evidence of scrolling. Keep the accepted anchor
+ // until enough independent columns move; do not turn local activity into loss.
+ if (columns.length < 3) {
+ const changedRows = Array.from({ length: height }, (_, y) => y).filter((y) => errorAt(previous, next, y, y, allColumns) >= 2);
+ const localRepaint = !changedRows.length || changedRows[changedRows.length - 1] - changedRows[0] + 1 <= Math.max(16, height * 0.1);
+ return { kind: localRepaint ? 'same' : 'unmatched' };
+ }
+ const rowErrors = Array.from({ length: height }, (_, y) => errorAt(previous, next, y, y, columns));
+ if (rowErrors.every((error) => error < 2)) return { kind: 'same' };
+ let header = 0;
+ let footer = 0;
+ const fixedLimit = Math.floor(height / 3);
+ while (header < fixedLimit && rowErrors[header] < 2) header++;
+ while (footer < fixedLimit && rowErrors[height - 1 - footer] < 2) footer++;
+ const end = height - footer;
+ const minimumOverlap = Math.max(24, Math.floor((end - header) * 0.2));
+ const candidates: Array<{ offset: number; score: number }> = [];
+ let bestScore = Infinity;
+ const maximumOffset = end - header - minimumOverlap;
+ // Compare both directions and zero motion. Otherwise a reverse scroll through
+ // similar paragraphs can masquerade as a weaker forward match and duplicate text.
+ for (let offset = -maximumOffset; offset <= maximumOffset; offset++) {
+ const start = header + Math.max(0, -offset);
+ const overlap = end - header - Math.abs(offset);
+ const rows = Math.min(48, overlap);
+ let sum = 0;
+ for (let sample = 0; sample < rows; sample++) {
+ const y = start + Math.floor((sample / rows) * overlap);
+ sum += errorAt(previous, next, y + offset, y, columns);
+ // Errors are nonnegative. Once a reliable candidate exists, an offset
+ // already outside its ambiguity margin can neither win nor invalidate it.
+ // Keep searching all offsets, but stop reading rows for this loser.
+ if (bestScore <= 3 && sum / rows > bestScore + Math.max(0.15, bestScore * 0.5)) break;
+ }
+ const score = sum / rows;
+ candidates.push({ offset, score });
+ bestScore = Math.min(bestScore, score);
+ }
+ candidates.sort((a, b) => a.score - b.score);
+ const best = candidates[0];
+ if (best?.offset < 0 && allowReverse) {
+ const reverse = matchSampledFrames(next, previous, false);
+ return reverse.kind === 'append' ? { ...reverse, kind: 'prepend', offset: -reverse.offset } : { kind: 'unmatched' };
+ }
+ if (best?.offset === 0 && (best.score <= 3 || rowErrors.filter((error) => error < 2).length / height >= 0.9)) return { kind: 'same' };
+ if (!best || best.offset <= 0 || best.score > 3) return { kind: 'unmatched' };
+ const rival = candidates.find((candidate) => Math.abs(candidate.offset - best.offset) > 2);
+ // White space dilutes the mean error on text pages. Compare relative confidence:
+ // an exact overlap must beat a similar-looking neighbouring paragraph, while
+ // genuinely repeated content (two equally good offsets) remains ambiguous.
+ if (rival && rival.score < best.score + Math.max(0.15, best.score * 0.5)) return { kind: 'unmatched' };
+ // Validate every row, rather than trusting the sparse search on repeated text.
+ let good = 0;
+ let sum = 0;
+ for (let y = header; y < end - best.offset; y++) {
+ const error = errorAt(previous, next, y + best.offset, y, columns);
+ sum += error;
+ if (error < 10) good++;
+ }
+ const count = end - header - best.offset;
+ if (sum / count > 6 || good / count < 0.9) return { kind: 'unmatched' };
+ return { kind: 'append', offset: best.offset, header, footer };
+}
+
+/** Owns only accepted frames. Failed matching keeps the last accepted anchor intact. */
+export class ScrollCapture {
+ private previous: RegionScreenshotBitmap;
+ private parts: Uint8Array<ArrayBuffer>[];
+ private rows: number;
+ private position = 0;
+ private top = 0;
+ private bottom = 0;
+
+ constructor(first: RegionScreenshotBitmap, private readonly maxPixels = 32_000_000) {
+ this.previous = first;
+ this.parts = [first.data];
+ this.rows = first.height;
+ }
+
+ get height(): number { return this.rows; }
+
+ add(frame: RegionScreenshotBitmap): ScrollMatch['kind'] | 'limit' {
+ const match = matchScrollFrames(this.previous, frame);
+ if (match.kind !== 'append' && match.kind !== 'prepend') return match.kind;
+ const position = this.position + match.offset;
+ const before = Math.max(0, this.top - position);
+ const after = Math.max(0, position - this.bottom);
+ const extension = before + after;
+ if (this.rows + extension > 32_768 || (this.rows + extension) * frame.width > this.maxPixels) return 'limit';
+ this.position = position;
+ this.previous = frame;
+ // Revisiting an already captured part moves the anchor, without duplicating it.
+ if (!extension) return 'same';
+ // The previous footer becomes stale; keep it exactly once at the final bottom.
+ const stride = frame.width * 4;
+ const remove = before ? match.header : match.footer;
+ if (remove) {
+ let remaining = remove * stride;
+ while (remaining && this.parts.length) {
+ const last = (before ? this.parts.shift() : this.parts.pop())!;
+ if (last.length > remaining) {
+ if (before) this.parts.unshift(last.subarray(remaining));
+ else this.parts.push(last.subarray(0, last.length - remaining));
+ remaining = 0;
+ } else remaining -= last.length;
+ }
+ this.rows -= remove;
+ }
+ const added = extension + remove;
+ if (before) this.parts.unshift(frame.data.slice(0, added * stride));
+ else this.parts.push(frame.data.slice((frame.height - added) * stride));
+ this.rows += added;
+ this.top = Math.min(this.top, position);
+ this.bottom = Math.max(this.bottom, position);
+ return before ? 'prepend' : 'append';
+ }
+
+ /** Preview reads only its visible rows; full export is assembled on demand. */
+ image(start = 0, count = this.rows): RegionScreenshotBitmap {
+ start = Math.max(0, Math.min(this.rows, Math.floor(start)));
+ const height = Math.max(0, Math.min(this.rows - start, Math.ceil(count)));
+ const stride = this.previous.width * 4;
+ const data = new Uint8Array(height * stride);
+ const from = start * stride, to = from + data.length;
+ let offset = 0;
+ for (const part of this.parts) {
+ const left = Math.max(from, offset), right = Math.min(to, offset + part.length);
+ if (right > left) data.set(part.subarray(left - offset, right - offset), left - from);
+ offset += part.length;
+ if (offset >= to) break;
+ }
+ return { width: this.previous.width, height, data };
+ }
+}
diff --git a/docs/design-rules/DESIGN.md b/docs/design-rules/DESIGN.md
index 8463f11fef..dadfcd6ee7 100644
--- a/docs/design-rules/DESIGN.md
+++ b/docs/design-rules/DESIGN.md
@@ -293,6 +293,7 @@ The grayscale rule is near-absolute. The following are the **only** sanctioned n
> - **Bot Unread Badge** — the Bots sidebar may paint its unread pill and its pending-todo dot in information blue `#417CDD` with white text (registered 2026-08-19). The color encodes **IM unread semantics** ("how much have I not seen"), the one signal every chat list has taught users to read by color alone; it is not a CTA and not a health/status tone. The pill was previously the inverse-CTA fill, which on the selected row's light-gray pill turned into two high-contrast marks competing for the same glance. Same value both modes — an unread count means the same thing in Light and Dark, and the value is already the registered focus-ring / Auto Approval / Toast-info blue. The foreground is a standalone white: `--accent-pure-cta-fg` flips to black in Dark and cannot be borrowed. Tokens: `--bot-unread-bg` / `--bot-unread-fg`. Scope is strictly teammate-list unread indicators in `features/bots`, including the Cindy device row, its device-picker options/trigger and the computer rows of the teammate 近况 popover (which replaced the chat-header picker on 2026-10-21), and — as a 6px dot only, never a text color — a group chat's 话题 unread marks: the thread entry under a root, the in-chat 话题 hint above the composer, its list rows and the thread panel's 「新回复」 divider (registered 2026-10-21, owner-approved r4 prototype; the words beside the dot stay `--text-primary`); Mobile mirrors the value as `botUnread` for the companion list row's unread dot only (registered 2026-09-29 — the host sends a boolean, so Mobile shows a dot, not a count) — do not reuse it for other badges, status dots, row backgrounds, or any other surface.
> - **Teammate todo due dot (registered 2026-10-21, owner request)** — a static 6px `--error-fg` dot (Mobile `statusError`, 7pt) meaning "this todo's own deadline is today or already passed". Exactly two placements, one shared component per platform (`TodoDueDot` in `features/bots/BotGlancePopover.tsx`): before the deadline text of the due row inside the teammate 近况 popover, and at the top-right of the chat-header 近况 entry (Mobile: the header avatar) while the owner has not opened 近况 since that item became due. The row dot stays until the item is handled or rescheduled; the entry dot clears on opening. No text, no breathing; the entry's accessible name carries the same information. It is not an error state and must not be reused for task errors, unread, or other badges.
> - **ConfirmDialog Danger** — `#EF4444` used ONLY on the confirm button background in the Danger variant. The cancel button and rest of the dialog remain grayscale.
+> - **Screenshot overlay and annotation ink (registered 2026-10-26, owner-approved)** — the global screenshot overlay and its pinned images draw on top of arbitrary screen content, so two small fixed sets live in `features/region-screenshot/screenshotColors.ts` and are the same in Light and Dark. **Annotation ink** (`SCREENSHOT_INK`): red `#FF3B30` (the `annotation-accent` value), yellow `#FFCC00`, green `#34C759`, blue `#007AFF`, black `#000000`, white `#FFFFFF`. Ink is burned into the user's screenshot; it is user content, not UI color. The color swatches in the annotation style bar show the ink itself, each inside a `--border-default` ring so black and white stay visible in both modes. **Functional overlay pixels** (`SCREENSHOT_OVERLAY`): the dim layer `rgba(0,0,0,0.45)` outside the selection, the 1px white selection edge with a `rgba(0,0,0,0.6)` outer ring, white resize handles, the dashed selected-annotation box, the magnifier crosshair band and the black backdrop under the frozen frame. These must stay legible over any wallpaper, window or video. Everything else in the screenshot UI (toolbar, style bar, AI menu, magnifier card and its text, size label, hint pill, pin zoom badge and pin border) uses theme tokens and the standard icon-button and CTA treatments. Do not reuse these values outside the screenshot overlay and pinned images.
> - **Permission Selector Mode Highlights** — selected risky permission modes may color only the option text/icon/checkmark and the collapsed trigger text/icon. The selected row background remains grayscale. Auto Approval uses `#417CDD` in both modes (finalized 2026-07-17, same value light/dark; replaces light #000050 / dark #00D9C5). Full Access uses Heart Orange `#EA6B17` in both modes (auto-follows warning-accent, finalized 2026-07-17). These hex values are the **default-theme palette only** — other themes may override `--perm-auto-selected-text` and `--perm-bypass-selected-text` with their own accent colors, provided both modes remain color-coded, distinguishable from each other, and visually distinct from neutral text. Tokens: `--perm-auto-selected-text` and `--perm-bypass-selected-text` in `apps/desktop/src/renderer/styles/globals.css`.
> - **Shared-task Owner Crown** — the small crown immediately after the Agent/status icon uses the existing gold foreground `#F3A115` in both modes (`--warning-fg` on Desktop, `warningFg` on Mobile). This is a narrowly registered identity mark: it appears only for tasks owned by the current account, stays gold on selected rows, and never colors the title, row background, guest tasks, or an empty placeholder.
> - **Diff Add Green / Diff Del Red** — GitHub-standard diff syntax colors, used on the `+` / `-` symbol glyph, the changed-line text foreground, **and the full row background** inside code-diff renderings. Applied in three places: (1) the Edit-tool DiffView card (F-MSG-6), (2) markdown ````diff`fenced code blocks in the message stream, and (3)`.diff`/`.patch`files opened in TextLightbox (the document previewer) — there hljs`.hljs-addition`/`.hljs-deletion`are forced`display: block`so the background fills to the right edge instead of stopping at the last glyph. Line-number gutter and ctx (unchanged) lines remain strictly grayscale per the layer system. **Foreground** — Add:`#22863a`Light /`#7ee787`Dark; Del:`#b31d28`Light /`#ff7b72`Dark. **Background** — Add:`#f0fff4`Light /`#033a16`Dark; Del:`#ffeef0`Light /`#67060c`Dark. Tokens:`--diff-add-fg/-bg`and`--diff-del-fg/-bg`in`apps/desktop/src/renderer/styles/globals.css`. Updated 2026-04-21: backgrounds switched from grayscale → GitHub red/green for full-row fill so additions / deletions are unambiguous at a glance.
@@ -374,6 +375,7 @@ _Positioning note: the Display / Section Heading / Sub-heading rows are conceptu
| 域 | 范围 | 允许 | 理由 |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 录屏倒计时 | `features/region-screenshot/LiveCapturePanel.tsx` 的倒计时数字 | 64px / 600 | 2026-10-27 用户要求显著放大录制倒计时;仅选区中央 160px 圆形提示使用此字号,控制条与其它文案仍遵守字号 token 阶梯。 |
| 登录 / Splash 品牌画布 | 桌面 `LoginControls.tsx`、`loginDesignTokens.ts`(Splash 借用同族面板)、`LegacyMigrationDialog.tsx`(仅字重)、`oauthResultPage.ts`(自包含品牌页生成器,raw CSS 为其常量载体);手机 `apps/mobile/app/(auth)/login.tsx`(登录页本体)、`apps/mobile/src/components/LoginSkinControls.tsx` 与 `apps/mobile/src/auth/loginSkinLayout.ts` | 700 + 设计 px 字号 | §16 已登记 Bold,两端共用同源登录画布与 figma 坐标系;桌面守卫只扫描 `apps/desktop/src/renderer`,手机端由自身守卫体系负责,本登记不扩展 PR #1553 的扫描范围 |
| markdown 内容 | **仅 Markdown 渲染路径**:桌面 Markdown 渲染器输出的 DOM `<strong>`(`MarkdownRenderer` 及其消费方;必须解析为绝对 700;嵌套 strong 仍封顶 700)、CodeMirror strong 语法节点(`codemirrorGithubTheme.ts` 的 `t.strong` → `fontWeight: 'bold'`)、移动端原生 Markdown strong(`apps/mobile/src/session/MessageRenderer.tsx` 的 `markdownStrong` → `fontWeight.bold`) | 700 / `bold` | 用户内容语义,非 UI chrome;编辑器内 strong 与两端渲染后的 strong 同权。DS-11 已在 `MarkdownRenderer` 的内容 strong 显式使用绝对 700,嵌套层同样封顶;不依赖 preflight 的相对 `bolder`。**本行不覆盖普通 UI chrome 里直接写的 `<strong>`**(如 `MakerExperimentalView.tsx` 会话状态与事件列表)——它们同样被 preflight 的相对 `bolder` 渲染成 700,但不属豁免域,是已登记缺口,待归一为 `font-medium` / `font-semibold`。 |
| hljs 主题移植 | `globals.css` 内 hljs 规则 | `bold` | 第三方主题移植,保真优先 |
@@ -397,6 +399,12 @@ _Positioning note: the Display / Section Heading / Sub-heading rows are conceptu
## 4. Component Stylings
+**Desktop scrolling screenshot flow (owner correction, 2026-10-26).** Scrolling capture stays in the original screenshot overlay: the selected area passes input to the source app, while the available space beside it contains a width-scaled, scrollable preview and edit/save/cancel/finish icons. Do not add a separate capture toolbar or result page. Finish copies and closes; Edit returns the stitched image to the existing annotation toolbar. Preview scaling must not reduce export resolution. All control chrome follows the same Light/Dark tokens as the ordinary toolbar. The draggable screen-top mode bar contains Screenshot, Scrolling screenshot, Region recording, GIF and Cindy, and appears only on the currently operated display. Switching modes does not start capture; after selection an explicit start action begins scrolling/recording. The bottom toolbar contains only annotation and export tools. Manual scrolling supports both directions without duplicating previously captured content; automatic scrolling can be stopped. Static or briefly unmatched frames do not immediately show a failure notice; persistent failure preserves the captured content and stops automatic scrolling.
+
+**Screenshot chrome safe area (owner request, 2026-10-27).** The selection may cover the whole display, but every piece of screenshot chrome (mode bar, hint, size label, magnifier, annotation toolbar and style bar, scrolling preview and its actions, recording controls) stays inside the display's chrome area: the system work area (no menu bar, Dock or taskbar), with the macOS camera housing (notch) also excluded when the menu bar is hidden. Live controls fall back to the rest of the display only when the selection leaves no room inside it. On macOS, a two-finger trackpad swipe never zooms a pinned image (pinch zooms it continuously around the pointer); pinch in the editor zooms around the pointer; one swipe, including its momentum, changes the snap level by one step.
+
+**Recording toolbar movement (owner request, 2026-10-27).** The grip, format, timer and their shared empty space form one drag target. Recording actions remain separate click targets. Releasing or cancelling a drag leaves the toolbar at its final accepted position, outside the capture region and within the same display's chrome area; delayed host replies must not move it back. Starting recording keeps the existing macOS panel's geometry and stacking unchanged.
+
> Buttons / Cards / Inputs below use the structured key-value format (adopted from the §12 pilot, 2026-07): `field → token → Default Light / Default Dark resolved values`. Token names per §10.
### Buttons
diff --git a/docs/design-rules/design-decision-log.md b/docs/design-rules/design-decision-log.md
index 4fe5e5e762..c382b611e6 100644
--- a/docs/design-rules/design-decision-log.md
+++ b/docs/design-rules/design-decision-log.md
@@ -12,6 +12,8 @@
## 2026-10
+- **10-26 滚动截图沿用截图流程,不新增独立面板**——用户指出缩小预览/保存面板割裂体验。滚动时保留原选区,在选区外预览拼接结果并提供编辑、保存、取消、完成;完成复制并关闭,编辑回原标注器。预览缩放不得降低导出尺寸。落点:`DESIGN.md §4`、`RegionScreenshotOverlay`、`ScrollCaptureOverlay`。
+
- **10-26 群聊顶栏群名下一行改为人数,不再列出所有成员**——用户指出群名下面把成员名用「、」平铺列满,跨账号的群里「Miao (dash)、Cindy (chris)、dash、Opus (dash)…」又长又乱,要求「不能列满」。现行:Desktop 与 Mobile 群聊顶栏群名下只写「N 位成员」(人与伙伴一起算,Desktop 用等宽数字),不再在这一行标「负责人」;Desktop 有人在发言、安排或做某一步时,这一行换成原有的进行中状态(✨「X 正在说…」),结束后回到人数;Mobile 群聊主界面始终显示人数,不做该状态切换。完整名单移到悬停提示(Desktop)与读屏标签(Mobile),群设置的成员列表不变;私聊仍显示对方名字。`memberCount` 文案由「N 位伙伴」改为「N 位成员」,因为群里也有人类成员,群设置抽屉同步受益。被取代:bot-group-chat.md §5「成员名单(负责人带标)」。落点:`BotGroupChatView.tsx` 顶栏、`BotGroupChatScreen.tsx` 副标题;单页场景 `group-chat --case crowded`。
- **10-24 手机退役「任务/伙伴」两种首页模式:伙伴与任务完全打平,和电脑一致**——用户指出伙伴段上线后抽屉里的「任务 | 伙伴」切换和标题范围菜单里的「伙伴」仍是一套独立筛选,既然伙伴已经并入任务首页就不应再有独立筛选。现行:首页只有一种;抽屉不再放任务/伙伴分段控件,标题范围菜单不再列出伙伴;首页搜索同时列出匹配的伙伴;伙伴未读显示在伙伴段行与头像条蓝点上。被取代:10-13 的任务/伙伴左右滑动切换、伙伴首页、分段计数与菜单键注意点(`menu-attention` 资源已删除)。旧版本存下的「上次停在伙伴页」偏好在下次写入时清除,不再恢复。落点:`DESIGN.md` 手机首页段落;`apps/mobile/src/session/HomeSurface.tsx`、`HomeTeammatesSection.tsx`、`useHomeMode.ts`。
@@ -932,3 +934,13 @@ Switch 解耦。插件插槽挂载同一个媒体组件,不再维护单独拖
### 2026-10-12: 手机版「我的消息气泡颜色」
用户在 iPhone 试用包上多轮调整后决定先提交手机版,桌面端暂不提交。预设定名为初稿、晨光、灵感、梦境、夜猫、项圈:「心动」是公司名不用;夹在灵感与梦境之间、辨识度不足的青绿色去掉,改为取品牌红色相的「项圈」。系统 ColorPicker 面板过重、大圆盘不好看,改为点选「自定义颜色」后才展开的彩虹色带。自定义色放宽柔化(浅色 30%、深色 18%),深色上限受 7:1 对比度约束。设置预览的描边与内边距按真实气泡(#5787 后的 border、compact 密度)对齐。实现见 DESIGN §2「Personal message bubble colors」。本条记录方案裁决,不代表最终视觉验收。
+
+### 2026-10-26: 截图模式入口移到屏幕顶部
+
+用户验收指出底部工具栏过密,要求将截图、滚动截图、区域录制、GIF 和 Cindy 放到屏幕顶部;底部保留标注和输出,滚动/录制框选后由开始按钮启动。用户随后明确“长截图改为滚动截图”“采集的单独工具栏也不要”。滚动过程中沿用原全屏截图浮层,选区内透明并把滚轮交给原窗口;选区外显示拼接缩略图与编辑、保存、取消、完成图标,自动滚动/停止滚动按钮贴近选区。支持手动向上和向下拼接,已截内容不重复追加;完成直接复制并关闭,编辑回原标注器,不增加结果页面。静止和短暂局部重绘不提示接不上,持续丢失重叠时停止自动滚动并保留已截内容。本条为产品方向与实现记录,实机验证以当次验收报告为准。
+
+双屏补验确认:顶部模式条只显示在鼠标当前操作的屏幕,鼠标跨屏后转移;非当前屏幕不常驻重复的工具栏和操作提示。
+
+顶部栏拖动补验确认:左侧独立手柄左右拖动,纵向保持在顶部;两端限制在当前屏幕内。拖动不切换模式、不触发选区,本次截图内保留各屏的位置,新截图恢复居中。
+
+滚动预览补充裁决(2026-10-26):用户指出窄缩略卡片与期望体验不同。预览优先使用选区旁可用空间,随选区宽度扩展、最大宽度 640 DIP,随内容增高至屏幕可用高度;图片按宽度保持比例,超高后在预览内滚动,不再随整图长度继续缩小。新增长图向下/向上扩展时分别跟随尾部/头部,停止增长时可滚轮回看。
diff --git a/docs/design-rules/design-inventory.md b/docs/design-rules/design-inventory.md
index d925eb06f4..72ba0aad89 100644
--- a/docs/design-rules/design-inventory.md
+++ b/docs/design-rules/design-inventory.md
@@ -11,7 +11,7 @@
生成命令:`pnpm design:inventory`。裸颜色匹配与 `scripts/hardcoded-color-audit.mjs` 共用 `scripts/shared/hardcoded-color-match.mjs`(HEX / RGB / HSL / OKLCH 等字面通道),两者在共享 matcher 内统一排除纯语义包装、注释及 PR 编号;数值颜色函数还需位于样式属性、CSS 声明/函数或任意值语境,普通文案字符串里的颜色函数文本不计入;字面 fallback 仍计入——语义 token 消费与注释引用不是迁移债务;裸圆角为粗粒度(`rounded*` class、`border-radius:` 与 React style 对象的 `borderRadius:`)。Token 计数为样式源里 `var(--token)` / `hsl(var(--token)` 的去重 ID 数;Mobile 的 ThemeColors / typeScale 等 RN 属性不计入此列,不能将 0 解释为未使用 Token。
-登记 surface 数:54。平台包含 Desktop 与 Mobile;静态入口发现不表示已迁移或已实机验证。
+登记 surface 数:58。平台包含 Desktop 与 Mobile;静态入口发现不表示已迁移或已实机验证。
| ID | 平台 | 标题 | 生产入口 | 可达组件 | 样式来源 | Token 数 | 裸颜色 | 裸圆角 |
| --- | --- | --- | --- | --- | --- | ---: | ---: | ---: |
@@ -43,6 +43,10 @@
| `desktop.skillhub.local` | desktop | SkillHub 本地技能 | hash `/skillhub/local` 及统一详情 `/skillhub/detail`(旧详情链接重定向) | InstallTargetPicker, PluginDevicePicker, PluginManagementLayout, RemoteSkillsPage, SkillCategoryFilterBar, SkillDetailLayout, SkillhubDetailRoute, SkillhubDetailView, SkillhubFeatureLayout, SkillhubHomeView, SkillhubLocalLayout, SkillhubMarketDetailView | apps/desktop/src/renderer/features/plugin/PluginDevicePicker.tsx, apps/desktop/src/renderer/features/plugin/PluginManagementLayout.tsx, apps/desktop/src/renderer/features/skillhub/RemoteSkillsPage.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubDetailRoute.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubDetailView.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubFeatureLayout.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubHomeView.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubLocalLayout.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubMarketDetailView.tsx, apps/desktop/src/renderer/features/skillhub/components/InstallTargetPicker.tsx, apps/desktop/src/renderer/features/skillhub/components/SkillCategoryFilterBar.tsx, apps/desktop/src/renderer/features/skillhub/components/SkillDetailLayout.tsx, apps/desktop/src/renderer/features/skillhub/skillhub-home.css | 39 | 0 | 45 |
| `desktop.skillhub.market` | desktop | SkillHub 市场 | hash `/skillhub/market`(SkillhubMarketListView) | InstallTargetPicker, MarketCard, MarketInfoEditDialog, SkillhubMarketDetailView, SkillhubMarketListView, VisibilityEditorDialog | apps/desktop/src/renderer/features/skillhub/SkillhubMarketDetailView.tsx, apps/desktop/src/renderer/features/skillhub/SkillhubMarketListView.tsx, apps/desktop/src/renderer/features/skillhub/components/HomeMarketCard.tsx, apps/desktop/src/renderer/features/skillhub/components/InstallTargetPicker.tsx, apps/desktop/src/renderer/features/skillhub/components/LocalSkillControls.tsx, apps/desktop/src/renderer/features/skillhub/components/MarketCard.tsx, apps/desktop/src/renderer/features/skillhub/components/MarketInfoEditDialog.tsx, apps/desktop/src/renderer/features/skillhub/components/MarketInstallStatus.tsx, apps/desktop/src/renderer/features/skillhub/components/MarketListError.tsx, apps/desktop/src/renderer/features/skillhub/components/MarketLocalSkills.tsx, apps/desktop/src/renderer/features/skillhub/components/MarketPreviewTree.tsx, apps/desktop/src/renderer/features/skillhub/components/OfficialSkillBadge.tsx, apps/desktop/src/renderer/features/skillhub/components/PlatformTagSelector.tsx, apps/desktop/src/renderer/features/skillhub/components/SkillCategoryFilterBar.tsx, apps/desktop/src/renderer/features/skillhub/components/SkillDetailLayout.tsx, apps/desktop/src/renderer/features/skillhub/components/SkillIcon.tsx, apps/desktop/src/renderer/features/skillhub/components/SkillTagList.tsx, apps/desktop/src/renderer/features/skillhub/components/TeamScopePicker.tsx, apps/desktop/src/renderer/features/skillhub/components/VisibilityEditorDialog.tsx | 42 | 0 | 35 |
| `desktop.window.computer-permission-guide` | desktop | 电脑使用权限引导 | `?view=computer-permission-guide` → ComputerPermissionGuideWindow;backdrop 同文件 | ComputerPermissionBackdrop, ComputerPermissionGuideWindow | apps/desktop/src/main/computer-permission-guide/MacComputerPermissionGuideNativeHost.ts, apps/desktop/src/main/computer-permission-guide/placement.ts, apps/desktop/src/main/computer-permission-guide/request.ts, apps/desktop/src/main/computer-permission-guide/switch-target.ts, apps/desktop/src/main/computer-permission-guide/window.ts, apps/desktop/src/renderer/components/settings/ComputerPermissionGuideWindow.tsx | 7 | 2 | 9 |
+| `desktop.window.recording-preview` | desktop | 录屏独立回放窗口 | `?recordingPreview=1` → renderer/recording-preview-entry.tsx(不走 router.tsx) | Button, RecordingPreview | apps/desktop/src/main/region-screenshot/recordingPreview.ts, apps/desktop/src/renderer/components/ui/button.css, apps/desktop/src/renderer/components/ui/button.tsx, apps/desktop/src/renderer/features/region-screenshot/RecordingPreview.tsx, apps/desktop/src/renderer/recording-preview-entry.tsx, apps/desktop/src/renderer/styles/generated/tokens.css, apps/desktop/src/renderer/styles/globals.css | 102 | 38 | 18 |
+| `desktop.window.region-screenshot` | desktop | 全局截图浮层 | `?regionScreenshot=1` → renderer/region-screenshot-entry.tsx(不走 router.tsx) | Button, Magnifier, RegionScreenshotOverlay, ScreenshotStyleBar, ScreenshotToolbar, Tip | apps/desktop/src/main/region-screenshot/compose.ts, apps/desktop/src/main/region-screenshot/editor.ts, apps/desktop/src/main/region-screenshot/index.ts, apps/desktop/src/main/region-screenshot/liveCapture.ts, apps/desktop/src/main/region-screenshot/overlays.ts, apps/desktop/src/main/region-screenshot/pageWindow.ts, apps/desktop/src/main/region-screenshot/pins.ts, apps/desktop/src/main/region-screenshot/recordingClipboard.ts, apps/desktop/src/main/region-screenshot/recordingPreview.ts, apps/desktop/src/main/region-screenshot/save.ts, apps/desktop/src/main/region-screenshot/session.ts, apps/desktop/src/main/region-screenshot/snapshotHost.ts, apps/desktop/src/renderer/components/ui/button.css, apps/desktop/src/renderer/components/ui/button.tsx, apps/desktop/src/renderer/components/ui/tooltip.tsx, apps/desktop/src/renderer/features/region-screenshot/LiveCapturePanel.tsx, apps/desktop/src/renderer/features/region-screenshot/Magnifier.tsx, apps/desktop/src/renderer/features/region-screenshot/PinView.tsx, apps/desktop/src/renderer/features/region-screenshot/RecordingPreview.tsx, apps/desktop/src/renderer/features/region-screenshot/RegionScreenshotOverlay.tsx, apps/desktop/src/renderer/features/region-screenshot/ScreenshotEditorViewport.tsx, apps/desktop/src/renderer/features/region-screenshot/ScreenshotErrorBoundary.tsx, apps/desktop/src/renderer/features/region-screenshot/ScreenshotToolbar.tsx, apps/desktop/src/renderer/features/region-screenshot/ScrollCaptureOverlay.tsx, apps/desktop/src/renderer/features/region-screenshot/annotations.ts, apps/desktop/src/renderer/features/region-screenshot/bridge.ts, apps/desktop/src/renderer/features/region-screenshot/captureRecorder.test.ts, apps/desktop/src/renderer/features/region-screenshot/captureRecorder.ts, apps/desktop/src/renderer/features/region-screenshot/gifenc.d.ts, apps/desktop/src/renderer/features/region-screenshot/screenshotColors.ts, apps/desktop/src/renderer/features/region-screenshot/screenshotTaskHandoff.ts, apps/desktop/src/renderer/features/region-screenshot/trackpad.ts, apps/desktop/src/renderer/features/region-screenshot/webmDuration.ts, apps/desktop/src/renderer/region-screenshot-entry.tsx, apps/desktop/src/renderer/styles/generated/tokens.css, apps/desktop/src/renderer/styles/globals.css | 105 | 50 | 48 |
+| `desktop.window.region-screenshot-editor` | desktop | 截图独立编辑窗口 | `?regionScreenshotEditor=1` → renderer/region-screenshot-entry.tsx(不走 router.tsx) | Button, RegionScreenshotOverlay, ScreenshotStyleBar, ScreenshotToolbar, Tip | apps/desktop/src/main/region-screenshot/editor.ts, apps/desktop/src/renderer/components/ui/button.css, apps/desktop/src/renderer/components/ui/button.tsx, apps/desktop/src/renderer/components/ui/tooltip.tsx, apps/desktop/src/renderer/features/region-screenshot/LiveCapturePanel.tsx, apps/desktop/src/renderer/features/region-screenshot/Magnifier.tsx, apps/desktop/src/renderer/features/region-screenshot/PinView.tsx, apps/desktop/src/renderer/features/region-screenshot/RecordingPreview.tsx, apps/desktop/src/renderer/features/region-screenshot/RegionScreenshotOverlay.tsx, apps/desktop/src/renderer/features/region-screenshot/ScreenshotEditorViewport.tsx, apps/desktop/src/renderer/features/region-screenshot/ScreenshotErrorBoundary.tsx, apps/desktop/src/renderer/features/region-screenshot/ScreenshotToolbar.tsx, apps/desktop/src/renderer/features/region-screenshot/ScrollCaptureOverlay.tsx, apps/desktop/src/renderer/features/region-screenshot/annotations.ts, apps/desktop/src/renderer/features/region-screenshot/bridge.ts, apps/desktop/src/renderer/features/region-screenshot/captureRecorder.test.ts, apps/desktop/src/renderer/features/region-screenshot/captureRecorder.ts, apps/desktop/src/renderer/features/region-screenshot/gifenc.d.ts, apps/desktop/src/renderer/features/region-screenshot/screenshotColors.ts, apps/desktop/src/renderer/features/region-screenshot/screenshotTaskHandoff.ts, apps/desktop/src/renderer/features/region-screenshot/trackpad.ts, apps/desktop/src/renderer/features/region-screenshot/webmDuration.ts, apps/desktop/src/renderer/region-screenshot-entry.tsx, apps/desktop/src/renderer/styles/generated/tokens.css, apps/desktop/src/renderer/styles/globals.css | 105 | 46 | 46 |
+| `desktop.window.region-screenshot-pin` | desktop | 截图贴图窗口 | `?regionScreenshotPin=1` → renderer/region-screenshot-pin-entry.tsx(不走 router.tsx) | PinView | apps/desktop/src/main/region-screenshot/pins.ts, apps/desktop/src/renderer/features/region-screenshot/PinView.tsx, apps/desktop/src/renderer/region-screenshot-pin-entry.tsx, apps/desktop/src/renderer/styles/generated/tokens.css, apps/desktop/src/renderer/styles/globals.css | 79 | 37 | 17 |
| `desktop.window.remote-desktop` | desktop | 远程桌面独立窗口 | `?remoteDesktopViewer=1` → renderer/remote-desktop-viewer-entry.tsx | Button, ConfirmDialog, FormField, Popover, RemoteDesktopViewerWindow, Select, Switch, Tip | apps/desktop/src/main/remote-desktop-viewer/connection.ts, apps/desktop/src/main/remote-desktop-viewer/credentials.ts, apps/desktop/src/main/remote-desktop-viewer/preferences.ts, apps/desktop/src/main/remote-desktop-viewer/registry.ts, apps/desktop/src/main/remote-desktop-viewer/resolutionMemory.ts, apps/desktop/src/main/remote-desktop-viewer/safety.ts, apps/desktop/src/main/remote-desktop-viewer/windows.ts, apps/desktop/src/renderer/components/ui/button.tsx, apps/desktop/src/renderer/components/ui/confirm-dialog.tsx, apps/desktop/src/renderer/components/ui/form-field.tsx, apps/desktop/src/renderer/components/ui/popover.tsx, apps/desktop/src/renderer/components/ui/select-parts.tsx, apps/desktop/src/renderer/components/ui/select.css, apps/desktop/src/renderer/components/ui/select.tsx, apps/desktop/src/renderer/components/ui/switch.tsx, apps/desktop/src/renderer/components/ui/tooltip.tsx, apps/desktop/src/renderer/features/remote-desktop/RemoteDesktopViewerWindow.tsx, apps/desktop/src/renderer/features/remote-desktop/viewerWindow.css, apps/desktop/src/renderer/remote-desktop-viewer-entry.tsx, apps/desktop/src/renderer/styles/generated/tokens.css, apps/desktop/src/renderer/styles/globals.css | 134 | 36 | 29 |
| `desktop.window.resource-usage` | desktop | 资源用量窗口 | `?resourceUsageWindow=1` → renderer/resource-usage-entry.tsx(不走 router.tsx) | ResourceUsageWindowLayout, ResourceUsageWindowRoot | apps/desktop/src/main/resource-usage-window/controller.ts, apps/desktop/src/main/resource-usage-window/ipc.ts, apps/desktop/src/main/resource-usage-window/open-sender.ts, apps/desktop/src/main/resource-usage-window/registry.ts, apps/desktop/src/main/resource-usage-window/window.ts, apps/desktop/src/renderer/components/resource-usage/ResourceUsageWindowLayout.tsx, apps/desktop/src/renderer/resource-usage-entry.tsx, apps/desktop/src/renderer/styles/generated/tokens.css, apps/desktop/src/renderer/styles/globals.css | 79 | 38 | 15 |
| `desktop.window.review-artifact-confirm` | desktop | Review 成果确认窗 | main/reviewer/reviewArtifactConfirmWindow.ts 内联 HTML/CSS(不走 renderer 路由) | reviewArtifactConfirmWindow | apps/desktop/src/main/reviewer/reviewArtifactConfirmWindow.ts | 8 | 18 | 2 |
@@ -219,6 +223,10 @@ Mobile 已由 DS-7 纳入同一台账(2026-09-10 静态入口发现),保
| `desktop.skillhub.local` | Codex(DS-9 影响核对)/ kirozeng(验收协调) | legacy | — | SkillhubDiffPanel 继承 DiffView 排版,文件比较和发布逻辑不变 | 同一 DiffView 的真实 Worker/长行/大字号验证;Skill Hub 真实网络长反馈未联调;2026-09-17 或 DS-10 开工前复查 |
| `desktop.skillhub.market` | Codex(DS-9 影响核对)/ kirozeng(验收协调) | legacy | — | SkillhubDiffPanel 复用 DiffView,列表/网络逻辑不变 | 真实 Diff 组件验证不等于市场流程完成;真实远端联调按 DS-10 平台清单继续安排;2026-09-17 或 DS-10 开工前复查 |
| `desktop.window.computer-permission-guide` | Codex(DS-9 影响核对)/ kirozeng(验收协调) | legacy | — | DS-9 保留现有专属表面;未改全局 Button/主题源,按共享依赖核影响 | 本批未直接改该入口;无真实实例的独立/原生/账号/插件场景保留原合同,未作完整运行验收;kirozeng 安排所需环境,Codex 核对,2026-09-17 或 DS-10 开工前复查 |
+| `desktop.window.recording-preview` | unassigned | legacy | — | 查现有标准组件与治理 §12 当前路线;按人工下一动作接管 | 保持现状;发现问题记下一动作,本张不修视觉 |
+| `desktop.window.region-screenshot` | unassigned | legacy | — | 查现有标准组件与治理 §12 当前路线;按人工下一动作接管 | 保持现状;发现问题记下一动作,本张不修视觉 |
+| `desktop.window.region-screenshot-editor` | unassigned | legacy | — | 查现有标准组件与治理 §12 当前路线;按人工下一动作接管 | 保持现状;发现问题记下一动作,本张不修视觉 |
+| `desktop.window.region-screenshot-pin` | unassigned | legacy | — | 查现有标准组件与治理 §12 当前路线;按人工下一动作接管 | 保持现状;发现问题记下一动作,本张不修视觉 |
| `desktop.window.remote-desktop` | unassigned | legacy | — | 查现有标准组件与治理 §12 当前路线;按人工下一动作接管 | 保持现状;发现问题记下一动作,本张不修视觉 |
| `desktop.window.resource-usage` | Codex(DS-9 影响核对)/ kirozeng(验收协调) | legacy | 外部主题导入保护 token(进程类别色) | DS-9 保留现有专属表面;未改全局 Button/主题源,按共享依赖核影响 | 本批未直接改该入口;无真实实例的独立/原生/账号/插件场景保留原合同,未作完整运行验收;kirozeng 安排所需环境,Codex 核对,2026-09-17 或 DS-10 开工前复查 |
| `desktop.window.review-artifact-confirm` | Codex(DS-9 影响核对)/ kirozeng(验收协调) | legacy | — | DS-9 保留现有专属表面;未改全局 Button/主题源,按共享依赖核影响 | 本批未直接改该入口;无真实实例的独立/原生/账号/插件场景保留原合同,未作完整运行验收;kirozeng 安排所需环境,Codex 核对,2026-09-17 或 DS-10 开工前复查 |
diff --git a/docs/dev-rules/electron-security-and-process-boundaries.md b/docs/dev-rules/electron-security-and-process-boundaries.md
index 7df34471ce..d116e6ec21 100644
--- a/docs/dev-rules/electron-security-and-process-boundaries.md
+++ b/docs/dev-rules/electron-security-and-process-boundaries.md
@@ -127,6 +127,43 @@ Renderer 可以负责组件渲染、交互状态、表单状态、展示数据
注释和测试中写明冲突点;例外只豁免冲突项,其余预热、就绪握手、安全配置、状态清理与故障
隔离要求仍然适用。
+截图贴图窗口(`main/region-screenshot/pins.ts`)采用按内容多实例、关闭销毁;
+2026-10-26 用户明确选择按需创建,不常驻备用 Renderer,接受首次贴图的加载时间。
+此例外仅豁免预热,不豁免首份图片绘制后才显示、专用 preload、来源校验与故障关闭;
+超时、崩溃或失去响应时关闭该贴图,不以黑窗替代内容。回归见该目录的
+`__tests__/windows.test.ts`。框选截图浮层按显示器隐藏预热, 未使用的预热壳可复用;
+截图结束后销毁用过的透明浮层, 避免下一次继承原生窗口的透明度与合成状态。
+结束后延迟 1 秒重新预热, 立即再次截图时按需创建; 首帧绘制确认前始终保持透明。
+macOS 浮层是不激活应用的面板(`type: 'panel'`):拿键盘焦点但不激活 Cindy,截图前的
+应用保持前台,菜单栏不切换,滚动截图时触控板滚动与惯性照常交给它;不得改回
+`app.focus({ steal: true })`。
+
+滚动截图与区域录制复用该浮层和会话 token,开始后把控制区移到选区之外。
+滚动截图在原透明浮层显示选区轮廓与侧边预览,只在预览和自动滚动按钮处接收鼠标。
+长图编辑交给独立无标题栏窗口,复用辅助窗口 controller,原浮层结束;首份图片绘制后才显示。
+录屏统一入口,框选后选择视频/GIF;3秒大号倒计时结束才采样。默认录入鼠标指针,不采集或叠加按键。
+录制中透明浮层仅在选区外的紧凑控制条接收鼠标,拖动范围由 main 限制在本屏选区外;
+macOS 开始采集保留面板的位置与层级,不调用会先隐藏再后置窗口的 `blur()`;
+控制条的拖柄、格式、计时与同组空白区域可拖动,按钮操作独立,松手按最终指针位置落定。
+标注预览按需展开。结束后把已编码字节交给无标题栏回放窗口,随即结束采集与全局 Escape。
+回放窗口复用辅助窗口 controller、独立轻量入口及最小 preload;只持有已完成结果和保存/复制能力,
+不授予屏幕、按键或路径访问。回放窗口在 main 单独登记播放器全屏权限,权限检查仍核对自有页面、
+顶层 frame 与请求地址,不升级为 app-content,不开放媒体采集或自动全屏;Esc 先退出全屏。
+macOS 在用户请求的回放窗口实际显示前激活应用,再聚焦回放窗口;隐藏预热与录制浮层不抢应用焦点。
+取消保存保留结果,关闭清理媒体 URL 与交互状态。
+复制 IPC 只接受当前预览 token,主机验证真实 sender 与顶层 frame,字节与格式取自主机保留的结果,
+不接受路径或任意文件参数。原生文件剪贴板复用 `fileClipboard.ts`,视频/GIF 保留原格式;
+复制失败保留预览供重试。落盘引用生命周期见媒体存储规则「录屏剪贴板」。此 IPC 仅本机回放窗使用,不进入 device-link 白名单。
+自动滚动同样校验所属窗口、顶层 frame、当前 token 和滚动模式;只向启动时选中的原窗口
+发送选区中心的向下滚动,原生侧再次核对命中的窗口/进程。停止、编辑、导出或退出后不再发起滚动。
+main 按所属窗口、顶层 frame 和当前 token 校验每次采集,只向面板发送裁剪后的像素;
+不授予 Renderer 通用屏幕媒体流,不扩大 device-link 的远程 IPC 白名单。
+Windows 滚动截图与录制由当前用户会话的截图 helper 直接读取已选矩形(单帧最多 3200 万像素),不启动 SYSTEM broker;
+macOS 复用本地 ScreenCaptureKit helper,main 裁剪后才跨 IPC。没有录制临时文件或音频采集。
+暂停停止采样,关闭、显示器变化或 Renderer 故障结束会话;异步迟到帧丢弃。
+视频与 GIF 在内存中编码;保存通过原生保存框选择导出路径,取消保存保留本次结果供重试。
+复制通过媒体总仓保留文件,并写入原生文件剪贴板。
+
`webviewTag` 默认关闭;受控例外目前只有两类——主界面与右侧栏子窗口(内置浏览器需要;
右侧栏整栏子窗口与页签弹出窗口共用 `main/right-sidebar-window/window.ts` 的
`createSidebarHostWindow` 工厂与 `sidebarWindowPreload`,`main/sidebar-tab-window/window.ts`
diff --git a/docs/dev-rules/media-storage-and-protocols.md b/docs/dev-rules/media-storage-and-protocols.md
index a6d84c8312..80b60c1ad7 100644
--- a/docs/dev-rules/media-storage-and-protocols.md
+++ b/docs/dev-rules/media-storage-and-protocols.md
@@ -158,6 +158,16 @@
必须验证媒体仓缓存不可用时快照仍可读取,以及重复打开、失败、取消和重试不新增业务引用;
不得将已有持久附件的同内容 blob 降级为可回收缓存。
+### 录屏剪贴板
+
+录屏预览点击复制后,经 `region-screenshot/recordingClipboard.ts` 核验视频/GIF 字节并用
+`integrationCachePut` 进入媒体总仓,以 `recording-clipboard:latest` 登记引用。它是不可重新生成的
+用户录制内容,使用 `isCache: false`,不能按可再生缓存逐出。关闭预览或退出应用保留最近成功复制
+的文件,以便继续粘贴;下一次复制成功后才移除本引用下的旧指纹,物理字节由统一回收器处理,
+不删除其他附件的引用。重复复制同一内容复用指纹与引用;失败只回滚本次新引用,保留旧剪贴板文件。
+异步入仓捕获账号与数据库,预览失效或账号变化时不发起剪贴板写入;操作不把仓内路径暴露给 Renderer。
+Windows 使用 CF_HDROP,macOS 使用文件 URL 剪贴板,视频/GIF 均按文件复制以保留完整内容。
+
## 读取、协议与边界
- 持久地址统一使用 `cindy-media://blobs/<sha256>.<ext>`。路径解析必须走
diff --git a/i18n/GLOSSARY.md b/i18n/GLOSSARY.md
index 3644f61e90..79070c78ba 100644
--- a/i18n/GLOSSARY.md
+++ b/i18n/GLOSSARY.md
@@ -623,6 +623,10 @@ Orca Worker 创建卡上的命名字段。它只是派活用的名字,不改
日志上报文案里对「App 自身运行日志」的用户可见说法。刻意不直接叫「日志」: 设置页同屏已有「日志目录」「Debug 日志」两处指本地文件, 而这里要表达的是被上报的那部分内容(基础设施运行记录, 不含对话)。proposed: 与「日志」的分工尚未产品裁决。
+### Scrolling Screenshot
+
+2026-10-26 用户指定截图功能统一称为滚动截图,突出滚动操作,不再使用长截图作为功能名称。
+
### Share Link
供应商分享的一次性链接:生成后 5 分钟内有效、只能使用一次。与共享任务的「邀请链接 / 邀请码」是不同的东西,不要混用。
diff --git a/i18n/glossary.json b/i18n/glossary.json
index fd140cd5a7..92f8ff925d 100644
--- a/i18n/glossary.json
+++ b/i18n/glossary.json
@@ -5,6 +5,7 @@
"sourceLocale": "en",
"punctuationExempt": ["desktop:settings.help.qnaFeedbackBodyTemplate"],
"terms": [
+ {"id":"scrolling-screenshot","status":"proposed","en":"Scrolling Screenshot","translations":{"zh-CN":"滚动截图","zh-TW":"捲動截圖","ja":"スクロールスクリーンショット","ko":"스크롤 스크린샷"},"checkCase":false,"note":"2026-10-26 用户指定截图功能统一称为滚动截图,突出滚动操作,不再使用长截图作为功能名称。"},
{"id": "archive-task", "status": "proposed", "en": "Archive", "translations": {"zh-CN": "归档", "zh-TW": "歸檔", "ja": "アーカイブ", "ko": "보관"}, "checkCase": false, "note": "任务归档动作。灵动岛完成卡按钮沿用既有任务归档确认框的译法,避免同一操作链路混用存档/归档或封存/歸檔;不在此条目裁决或批量修改其它语境。"},
{"id": "speech-speed", "status": "proposed", "en": "Speech speed", "translations": {"zh-CN": "语速", "zh-TW": "語速", "ja": "読み上げ速度", "ko": "읽기 속도"}, "checkCase": false, "note": "伙伴语音设置的合成语速;按伙伴保存,通话朗读、消息朗读和试听共用。区别于播放器倍速和语音输入停顿时间。"},
{"id": "read-by-sentence", "status": "proposed", "en": "Read by sentence", "translations": {"zh-CN": "按句朗读", "zh-TW": "逐句朗讀", "ja": "文ごとに読み上げ", "ko": "문장별로 읽기"}, "checkCase": false, "note": "伙伴语音设置:默认在最终答复生成过程中按完整句子提前朗读;关闭后等待完整回复。需要回复后处理或无法识别最终答复阶段时延后。"},
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e0ccf08275..1de5721f12 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -392,6 +392,9 @@ importers:
fix-path:
specifier: ^5.0.0
version: 5.0.0
+ gifenc:
+ specifier: 1.0.3
+ version: 1.0.3
gray-matter:
specifier: ^4.0.3
version: 4.0.3
@@ -7632,6 +7635,9 @@ packages:
resolution: {integrity: sha512-VilgtJj/ALgGY77fiLam5iD336eSWi96Q15JSAG1zi8NRBysm3LXKdGnHb4m5cuyxvOLQQKWpBZAT6ni4FI2iQ==}
engines: {node: '>=6'}
+ resolution: {integrity: sha512-xdr6AdrfGBcfzncONUOlXMBuc5wJDtOueE3c5rdG0oNgtINLD+f2iFZltrBRZYzACRbKr+mSVU/x98zv2u3jmw==}
+
resolution: {integrity: sha512-SyHy3T1v2NUXn29OsWdxmK6RwHD+vkj3v8en8AOBZ1wBQ/hCAQ5bAQTD02kW4W9tUp/3Qh6J8r9EvntiyCmOOw==}
@@ -18717,6 +18723,8 @@ snapshots:
+
diff --git a/scripts/__tests__/design-inventory.test.mjs b/scripts/__tests__/design-inventory.test.mjs
index 7c1275e6a1..b6739eef86 100644
--- a/scripts/__tests__/design-inventory.test.mjs
+++ b/scripts/__tests__/design-inventory.test.mjs
@@ -58,7 +58,7 @@ test('DS-8: every desktop globals.css surface includes its generated token style
const { surfaces } = buildGeneratedSurfaces(ROOT);
const consumers = surfaces.filter(surface => surface.platform === 'desktop'
&& surface.styleSources.includes('apps/desktop/src/renderer/styles/globals.css'));
- assert.equal(consumers.length, 5);
+ assert.equal(consumers.length, 9);
for (const surface of consumers) {
assert.ok(surface.styleSources.includes('apps/desktop/src/renderer/styles/generated/tokens.css'), surface.id);
}
@@ -1011,11 +1011,15 @@ test('裸圆角统计覆盖 React style 对象的 camelCase borderRadius', () =>
test('renderer 模块图入口双向核对: index.tsx 的参数→入口模块映射必须与 catalog 一致', () => {
const actualEntries = extractRendererEntries(fs.readFileSync(RENDERER_INDEX_PATH, 'utf8'));
- // 与源码实况钉死:当前 3 个参数各自加载的入口模块。
+ // 治理合同 §2.1:独立编辑/回放窗口也必须登记,避免入口扫描错位或遗漏样式。
assert.deepEqual(Object.fromEntries(actualEntries), {
+ recordingPreview: './recording-preview-entry',
remoteDesktopViewer: './remote-desktop-viewer-entry',
resourceUsageWindow: './resource-usage-entry',
sidebarWindow: './sidebar-window-entry',
+ regionScreenshot: './region-screenshot-entry',
+ regionScreenshotEditor: './region-screenshot-entry',
+ regionScreenshotPin: './region-screenshot-pin-entry',
});
const covered = new Map(
catalogSurfaces().flatMap((surface) =>
diff --git a/scripts/hardcoded-color-exemptions.json b/scripts/hardcoded-color-exemptions.json
index 4fcddfc92f..5fb3c941a1 100644
--- a/scripts/hardcoded-color-exemptions.json
+++ b/scripts/hardcoded-color-exemptions.json
@@ -522,5 +522,68 @@
"glob": "docs/design-rules/design-inventory.md",
"reason": "台账 GENERATED 区块自述计数口径(`hsl(var(--token)`),同 DESIGN.md 文档示例先例",
"owner": "design-system"
+ },
+ {
+ "glob": "apps/desktop/src/renderer/features/region-screenshot/screenshotColors.ts",
+ "reason": "全局截图的标注墨水 (烧录进用户截图的内容像素, 红色即 annotation-accent) 与覆盖在任意屏幕内容上的功能像素 (暗化遮罩、选区白描边与暗色外圈、放大镜十字线、定格底色): 不是界面语义色, 两种模式必须同值才能在任何底色上看清; 界面 chrome 仍走 token。DESIGN.md §2「Screenshot overlay and annotation ink」登记",
+ "owner": "region-screenshot",
+ "reviewDate": "2027-04-26",
+ "matches": [
+ {
+ "value": "#FF3B30",
+ "before": "red:\\s*['\\\"]",
+ "object": "SCREENSHOT_INK"
+ },
+ {
+ "value": "#FFCC00",
+ "before": "yellow:\\s*['\\\"]",
+ "object": "SCREENSHOT_INK"
+ },
+ {
+ "value": "#34C759",
+ "before": "green:\\s*['\\\"]",
+ "object": "SCREENSHOT_INK"
+ },
+ {
+ "value": "#007AFF",
+ "before": "blue:\\s*['\\\"]",
+ "object": "SCREENSHOT_INK"
+ },
+ {
+ "value": "#000000",
+ "before": "black:\\s*['\\\"]",
+ "object": "SCREENSHOT_INK"
+ },
+ {
+ "value": "#FFFFFF",
+ "before": "white:\\s*['\\\"]",
+ "object": "SCREENSHOT_INK"
+ },
+ {
+ "value": "#000000",
+ "before": "backdrop:\\s*['\\\"]",
+ "object": "SCREENSHOT_OVERLAY"
+ },
+ {
+ "value": "rgba(0, 0, 0, 0.45)",
+ "before": "shade:\\s*['\\\"]",
+ "object": "SCREENSHOT_OVERLAY"
+ },
+ {
+ "value": "#FFFFFF",
+ "before": "edge:\\s*['\\\"]",
+ "object": "SCREENSHOT_OVERLAY"
+ },
+ {
+ "value": "rgba(0, 0, 0, 0.6)",
+ "before": "edgeOuter:\\s*['\\\"]",
+ "object": "SCREENSHOT_OVERLAY"
+ },
+ {
+ "value": "rgba(0, 0, 0, 0.35)",
+ "before": "crosshair:\\s*['\\\"]",
+ "object": "SCREENSHOT_OVERLAY"
+ }
+ ]
}
]
diff --git a/scripts/shared/design-inventory.mjs b/scripts/shared/design-inventory.mjs
index 79945cff39..42e3d055ba 100644
--- a/scripts/shared/design-inventory.mjs
+++ b/scripts/shared/design-inventory.mjs
@@ -793,6 +793,82 @@ export function catalogSurfaces() {
routerPaths: [],
rendererEntryModules: { resourceUsageWindow: './resource-usage-entry' },
},
+ {
+ id: 'desktop.window.region-screenshot',
+ platform: 'desktop',
+ title: '全局截图浮层',
+ productionEntry:
+ '`?regionScreenshot=1` → renderer/region-screenshot-entry.tsx(不走 router.tsx)',
+ reachableComponents: ['RegionScreenshotOverlay', 'ScreenshotToolbar', 'ScreenshotStyleBar', 'Magnifier', 'Button', 'Tip'],
+ styleRoots: [
+ 'apps/desktop/src/renderer/region-screenshot-entry.tsx',
+ 'apps/desktop/src/renderer/features/region-screenshot',
+ 'apps/desktop/src/renderer/components/ui/button.tsx',
+ 'apps/desktop/src/renderer/components/ui/button.css',
+ 'apps/desktop/src/renderer/components/ui/tooltip.tsx',
+ 'apps/desktop/src/main/region-screenshot',
+ 'apps/desktop/src/renderer/styles/globals.css',
+ 'apps/desktop/src/renderer/styles/generated/tokens.css',
+ ],
+ routerPaths: [],
+ rendererEntryModules: { regionScreenshot: './region-screenshot-entry' },
+ },
+ {
+ id: 'desktop.window.region-screenshot-editor',
+ platform: 'desktop',
+ title: '截图独立编辑窗口',
+ productionEntry:
+ '`?regionScreenshotEditor=1` → renderer/region-screenshot-entry.tsx(不走 router.tsx)',
+ reachableComponents: ['RegionScreenshotOverlay', 'ScreenshotToolbar', 'ScreenshotStyleBar', 'Button', 'Tip'],
+ styleRoots: [
+ 'apps/desktop/src/renderer/region-screenshot-entry.tsx',
+ 'apps/desktop/src/renderer/features/region-screenshot',
+ 'apps/desktop/src/renderer/components/ui/button.tsx',
+ 'apps/desktop/src/renderer/components/ui/button.css',
+ 'apps/desktop/src/renderer/components/ui/tooltip.tsx',
+ 'apps/desktop/src/main/region-screenshot/editor.ts',
+ 'apps/desktop/src/renderer/styles/globals.css',
+ 'apps/desktop/src/renderer/styles/generated/tokens.css',
+ ],
+ routerPaths: [],
+ rendererEntryModules: { regionScreenshotEditor: './region-screenshot-entry' },
+ },
+ {
+ id: 'desktop.window.recording-preview',
+ platform: 'desktop',
+ title: '录屏独立回放窗口',
+ productionEntry:
+ '`?recordingPreview=1` → renderer/recording-preview-entry.tsx(不走 router.tsx)',
+ reachableComponents: ['RecordingPreview', 'Button'],
+ styleRoots: [
+ 'apps/desktop/src/renderer/recording-preview-entry.tsx',
+ 'apps/desktop/src/renderer/features/region-screenshot/RecordingPreview.tsx',
+ 'apps/desktop/src/renderer/components/ui/button.tsx',
+ 'apps/desktop/src/renderer/components/ui/button.css',
+ 'apps/desktop/src/main/region-screenshot/recordingPreview.ts',
+ 'apps/desktop/src/renderer/styles/globals.css',
+ 'apps/desktop/src/renderer/styles/generated/tokens.css',
+ ],
+ routerPaths: [],
+ rendererEntryModules: { recordingPreview: './recording-preview-entry' },
+ },
+ {
+ id: 'desktop.window.region-screenshot-pin',
+ platform: 'desktop',
+ title: '截图贴图窗口',
+ productionEntry:
+ '`?regionScreenshotPin=1` → renderer/region-screenshot-pin-entry.tsx(不走 router.tsx)',
+ reachableComponents: ['PinView'],
+ styleRoots: [
+ 'apps/desktop/src/renderer/region-screenshot-pin-entry.tsx',
+ 'apps/desktop/src/renderer/features/region-screenshot/PinView.tsx',
+ 'apps/desktop/src/main/region-screenshot/pins.ts',
+ 'apps/desktop/src/renderer/styles/globals.css',
+ 'apps/desktop/src/renderer/styles/generated/tokens.css',
+ ],
+ routerPaths: [],
+ rendererEntryModules: { regionScreenshotPin: './region-screenshot-pin-entry' },
+ },
{
id: 'desktop.window.remote-desktop',
platform: 'desktop',