feat: add macOS screen snapshots for monitor preview (#67954) thanks @BunsDev

Co-authored-by: Val Alexander <68980965+BunsDev@users.noreply.github.com>

apps/macos/Sources/OpenClaw/NodeMode/MacNodeModeCoordinator.swift

@@ -146,6 +146,7 @@ final class MacNodeModeCoordinator {
             OpenClawCanvasA2UICommand.push.rawValue,
             OpenClawCanvasA2UICommand.pushJSONL.rawValue,
             OpenClawCanvasA2UICommand.reset.rawValue,
+            MacNodeScreenCommand.snapshot.rawValue,
             MacNodeScreenCommand.record.rawValue,
             OpenClawSystemCommand.notify.rawValue,
             OpenClawSystemCommand.which.rawValue,

apps/macos/Sources/OpenClaw/NodeMode/MacNodeRuntime.swift

@@ -63,6 +63,8 @@ actor MacNodeRuntime {
                 return try await self.handleCameraInvoke(req)
             case OpenClawLocationCommand.get.rawValue:
                 return try await self.handleLocationInvoke(req)
+            case MacNodeScreenCommand.snapshot.rawValue:
+                return try await self.handleScreenSnapshotInvoke(req)
             case MacNodeScreenCommand.record.rawValue:
                 return try await self.handleScreenRecordInvoke(req)
             case OpenClawSystemCommand.run.rawValue:
@@ -352,6 +354,34 @@ actor MacNodeRuntime {
         return BridgeInvokeResponse(id: req.id, ok: true, payloadJSON: payload)
     }
 
+    private func handleScreenSnapshotInvoke(_ req: BridgeInvokeRequest) async throws -> BridgeInvokeResponse {
+        let params = (try? Self.decodeParams(MacNodeScreenSnapshotParams.self, from: req.paramsJSON)) ??
+            MacNodeScreenSnapshotParams()
+        let services = await self.mainActorServices()
+        let capturedAtMs = Int64(Date().timeIntervalSince1970 * 1000)
+        let res = try await services.snapshotScreen(
+            screenIndex: params.screenIndex,
+            maxWidth: params.maxWidth,
+            quality: params.quality,
+            format: params.format)
+        struct ScreenSnapshotPayload: Encodable {
+            var format: String
+            var base64: String
+            var width: Int
+            var height: Int
+            var screenIndex: Int?
+            var capturedAtMs: Int64
+        }
+        let payload = try Self.encodePayload(ScreenSnapshotPayload(
+            format: res.format.rawValue,
+            base64: res.data.base64EncodedString(),
+            width: res.width,
+            height: res.height,
+            screenIndex: params.screenIndex,
+            capturedAtMs: capturedAtMs))
+        return BridgeInvokeResponse(id: req.id, ok: true, payloadJSON: payload)
+    }
+
     private func mainActorServices() async -> any MacNodeRuntimeMainActorServices {
         if let cachedMainActorServices { return cachedMainActorServices }
         let services = await self.makeMainActorServices()

apps/macos/Sources/OpenClaw/NodeMode/MacNodeRuntimeMainActorServices.swift

@@ -4,6 +4,13 @@ import OpenClawKit
 
 @MainActor
 protocol MacNodeRuntimeMainActorServices: Sendable {
+    func snapshotScreen(
+        screenIndex: Int?,
+        maxWidth: Int?,
+        quality: Double?,
+        format: OpenClawScreenSnapshotFormat?) async throws
+        -> (data: Data, format: OpenClawScreenSnapshotFormat, width: Int, height: Int)
+
     func recordScreen(
         screenIndex: Int?,
         durationMs: Int?,
@@ -21,9 +28,24 @@ protocol MacNodeRuntimeMainActorServices: Sendable {
 
 @MainActor
 final class LiveMacNodeRuntimeMainActorServices: MacNodeRuntimeMainActorServices, @unchecked Sendable {
+    private let screenSnapshotter = ScreenSnapshotService()
     private let screenRecorder = ScreenRecordService()
     private let locationService = MacNodeLocationService()
 
+    func snapshotScreen(
+        screenIndex: Int?,
+        maxWidth: Int?,
+        quality: Double?,
+        format: OpenClawScreenSnapshotFormat?) async throws
+        -> (data: Data, format: OpenClawScreenSnapshotFormat, width: Int, height: Int)
+    {
+        try await self.screenSnapshotter.snapshot(
+            screenIndex: screenIndex,
+            maxWidth: maxWidth,
+            quality: quality,
+            format: format)
+    }
+
     func recordScreen(
         screenIndex: Int?,
         durationMs: Int?,

apps/macos/Sources/OpenClaw/NodeMode/MacNodeScreenCommands.swift

@@ -1,9 +1,18 @@
 import Foundation
+import OpenClawKit
 
 enum MacNodeScreenCommand: String, Codable {
+    case snapshot = "screen.snapshot"
     case record = "screen.record"
 }
 
+struct MacNodeScreenSnapshotParams: Codable, Equatable {
+    var screenIndex: Int?
+    var maxWidth: Int?
+    var quality: Double?
+    var format: OpenClawScreenSnapshotFormat?
+}
+
 struct MacNodeScreenRecordParams: Codable, Equatable {
     var screenIndex: Int?
     var durationMs: Int?

apps/macos/Sources/OpenClaw/ScreenSnapshotService.swift

@@ -0,0 +1,109 @@
+import AppKit
+import Foundation
+import OpenClawKit
+@preconcurrency import ScreenCaptureKit
+
+@MainActor
+final class ScreenSnapshotService {
+    enum ScreenSnapshotError: LocalizedError {
+        case noDisplays
+        case invalidScreenIndex(Int)
+        case captureFailed(String)
+        case encodeFailed(String)
+
+        var errorDescription: String? {
+            switch self {
+            case .noDisplays:
+                "No displays available for screen snapshot"
+            case let .invalidScreenIndex(idx):
+                "Invalid screen index \(idx)"
+            case let .captureFailed(message):
+                message
+            case let .encodeFailed(message):
+                message
+            }
+        }
+    }
+
+    func snapshot(
+        screenIndex: Int?,
+        maxWidth: Int?,
+        quality: Double?,
+        format: OpenClawScreenSnapshotFormat?) async throws
+        -> (data: Data, format: OpenClawScreenSnapshotFormat, width: Int, height: Int)
+    {
+        let format = format ?? .jpeg
+        let normalized = Self.normalize(maxWidth: maxWidth, quality: quality, format: format)
+
+        let content = try await SCShareableContent.current
+        let displays = content.displays.sorted { $0.displayID < $1.displayID }
+        guard !displays.isEmpty else {
+            throw ScreenSnapshotError.noDisplays
+        }
+
+        let idx = screenIndex ?? 0
+        guard idx >= 0, idx < displays.count else {
+            throw ScreenSnapshotError.invalidScreenIndex(idx)
+        }
+        let display = displays[idx]
+
+        let filter = SCContentFilter(display: display, excludingWindows: [])
+        let config = SCStreamConfiguration()
+        let targetSize = Self.targetSize(
+            width: display.width,
+            height: display.height,
+            maxWidth: normalized.maxWidth)
+        config.width = targetSize.width
+        config.height = targetSize.height
+        config.showsCursor = true
+
+        let cgImage: CGImage
+        do {
+            cgImage = try await SCScreenshotManager.captureImage(
+                contentFilter: filter,
+                configuration: config)
+        } catch {
+            throw ScreenSnapshotError.captureFailed(error.localizedDescription)
+        }
+
+        let bitmap = NSBitmapImageRep(cgImage: cgImage)
+        let data: Data
+        switch format {
+        case .png:
+            guard let encoded = bitmap.representation(using: .png, properties: [:]) else {
+                throw ScreenSnapshotError.encodeFailed("png encode failed")
+            }
+            data = encoded
+        case .jpeg:
+            guard let encoded = bitmap.representation(
+                using: .jpeg,
+                properties: [.compressionFactor: normalized.quality])
+            else {
+                throw ScreenSnapshotError.encodeFailed("jpeg encode failed")
+            }
+            data = encoded
+        }
+
+        return (data: data, format: format, width: cgImage.width, height: cgImage.height)
+    }
+
+    private static func normalize(
+        maxWidth: Int?,
+        quality: Double?,
+        format: OpenClawScreenSnapshotFormat)
+        -> (maxWidth: Int, quality: Double)
+    {
+        let resolvedMaxWidth = maxWidth.flatMap { $0 > 0 ? $0 : nil } ?? (format == .png ? 900 : 1600)
+        let resolvedQuality = min(1.0, max(0.05, quality ?? 0.72))
+        return (maxWidth: resolvedMaxWidth, quality: resolvedQuality)
+    }
+
+    private static func targetSize(width: Int, height: Int, maxWidth: Int) -> (width: Int, height: Int) {
+        guard width > 0, height > 0, width > maxWidth else {
+            return (width: width, height: height)
+        }
+        let scale = Double(maxWidth) / Double(width)
+        let targetHeight = max(1, Int((Double(height) * scale).rounded()))
+        return (width: maxWidth, height: targetHeight)
+    }
+}