Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

feat(spaces): Space thumbnails in the daemon and SDK; blurred connecting preview and an auto-connect setting (#4442)

ddupont7b98efd35b50
diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/AppModel.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/AppModel.swift
index e212d65ef3..69a372c79b 100644
--- a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/AppModel.swift
+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/AppModel.swift
@@ -142,6 +142,9 @@ public final class AppModel {
hostArch: Self.hostArch, storage: nil, cloudPricing: nil, clouds: [], hosts: [],
experiments: settings.experiments, gpus: nil))
self.notch = NotchModel()
+ // The notch tiles and the preview cover read one thumbnail store,
+ // filled from the SDK's shared cache.
+ notch.thumbnails.fetch = { [backend] id, maxAgeMs in await backend.thumbnail(id: id, maxAgeMs: maxAgeMs) }
// The app core's usage events for each step (the Tauri app sends
// the same ones): the first run, Settings, Storage, enrollment.
onboarding.telemetry = telemetry
@@ -217,6 +220,23 @@ public final class AppModel {
return spaces.first { $0.id == id }
}
+ /// Every Space's latest thumbnail: the notch tiles' and the preview
+ /// cover's one store.
+ public var thumbnails: SpaceThumbnails { notch.thumbnails }
+
+ /// The Spaces that can stream now (running and reachable).
+ public var streamableSpaceIds: [String] {
+ spaces.filter { appSpaceDetail(space: $0).canStream }.map(\.id)
+ }
+
+ /// What the Space's preview card shows over (or instead of) its live
+ /// desktop, from the core.
+ public func cover(_ detail: AppSpaceDetail, requested: Bool, stream: AppStreamPhase) -> AppDesktopCover {
+ appDesktopCover(input: AppDesktopCoverInput(
+ canStream: detail.canStream, previewText: detail.previewText,
+ autoConnect: settings.autoConnect, connectRequested: requested, stream: stream))
+ }
+
/// The detail without what Settings, Experiments hides (Share while
/// Sharing is off).
public func detail(_ space: AppSpace) -> AppSpaceDetail {
@@ -330,6 +350,10 @@ public final class AppModel {
recompose()
loaded = true
if selection == nil, let first = sidebar.selectedId { selection = .space(first) }
+ // A preview for every running Space from the daemon's cache
+ // (it survives restarts), before one is opened.
+ let running = streamableSpaceIds
+ Task { await thumbnails.warm(running) }
} catch {
show(error: "Could not list Spaces: \(LiveSpacesBackend.words(error))")
}
@@ -620,7 +644,8 @@ public final class AppModel {
menuBar: settings.menuBar, defaultLocation: settings.defaultLocation, locationLockedBy: nil,
telemetry: telemetryInput, agents: agentRows, agentsBusy: agentsBusy, agentsPending: agentsPending,
billing: identity == nil ? nil : billingStatus, loginItem: loginItemInput,
- experiments: settings.experiments, keyvaultAutoWipe: keyvault.autoWipe))
+ experiments: settings.experiments, keyvaultAutoWipe: keyvault.autoWipe,
+ autoConnect: settings.autoConnect))
}
/// Settings, General with Settings, Storage after General while the Cua
@@ -758,6 +783,9 @@ public final class AppModel {
case "default-location":
settings.defaultLocation = option == "cloud" ? .cloud : .local
saveSettings()
+ case "auto-connect":
+ settings.autoConnect = option == "on"
+ saveSettings()
case "launch-at-login":
setLaunchAtLogin(option == "on")
case "keyvault-auto-wipe":
diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/NotchModel.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/NotchModel.swift
index bbf65acb1e..52c5471527 100644
--- a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/NotchModel.swift
+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/NotchModel.swift
@@ -39,8 +39,9 @@ public final class NotchModel {
public var spaces: [AppSpace] = []
/// A captured image of the dragged window (the additive ghost).
public private(set) var ghost: NSImage?
- /// Latest screenshot per Space id, for the tiles.
- public var thumbnails: [String: NSImage] = [:]
+ /// Latest thumbnail per Space id, for the tiles: the same store the
+ /// detail's preview cover reads (`AppModel.thumbnails`).
+ public let thumbnails = SpaceThumbnails()
/// A forced hover or pressed look on one control (snapshot tests and
/// debug start states only; real input never sets it).
public var highlight: NotchHighlight?
diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/SpaceThumbnails.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/SpaceThumbnails.swift
new file mode 100644
index 0000000000..e251e5587e
--- /dev/null
+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/SpaceThumbnails.swift
@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: FSL-1.1-MIT
+// Copyright (c) 2026 Cua AI, Inc.
+
+import AppKit
+import CoreImage
+import CoreVideo
+import CuaSpacesFFI
+import Foundation
+
+/// A Space's thumbnail as the SDK returns it (`Space.thumbnail`): the
+/// encoded image and when it was captured.
+public struct SpaceThumbnailData: Sendable, Equatable {
+ public var image: Data
+ public var capturedAt: Date
+
+ public init(image: Data, capturedAt: Date) {
+ self.image = image
+ self.capturedAt = capturedAt
+ }
+}
+
+/// The app's in-memory layer over the SDK's thumbnail cache (the cua
+/// daemon's, shared by every client on this Mac): the latest image per
+/// Space, so the notch tiles and the preview cover paint at once. The
+/// notch and the cover read the same entry; nothing here captures a
+/// screen itself.
+///
+/// - `refresh(_:maxAge:)` asks the SDK for an image no older than `maxAge`
+/// (the daemon answers from its cache, or captures).
+/// - `warm(_:)` fills Spaces with no image yet from the daemon's cache
+/// (any age), so a preview exists right after launch.
+/// - `keepFresh` asks again for every running Space every
+/// `backgroundInterval` while the app is visible and not in Low Power
+/// Mode, which also keeps the daemon's own background refresh going.
+@MainActor
+@Observable
+public final class SpaceThumbnails {
+ public struct Entry: Equatable {
+ public var image: NSImage
+ public var capturedAt: Date
+ }
+
+ public private(set) var entries: [String: Entry] = [:]
+ /// The SDK call (`Space.thumbnail(maxAgeMs:)`); none: memory only.
+ @ObservationIgnored public var fetch: ((String, UInt64?) async -> SpaceThumbnailData?)?
+ @ObservationIgnored private var inFlight: Set<String> = []
+ /// Spaces `warm` already asked about (once each per launch).
+ @ObservationIgnored private var warmed: Set<String> = []
+ @ObservationIgnored private var keeping: Task<Void, Never>?
+ public static let policy = appThumbnailPolicy()
+
+ public init() {}
+
+ /// The Space's latest image, read synchronously (nil: none yet).
+ public subscript(id: String) -> NSImage? {
+ get { entries[id]?.image }
+ set {
+ if let newValue { set(id, newValue) } else { remove(id) }
+ }
+ }
+
+ /// Keeps `image` as the Space's latest, unless a newer one is held.
+ public func set(_ id: String, _ image: NSImage, at capturedAt: Date = Date()) {
+ if let held = entries[id], held.capturedAt > capturedAt { return }
+ entries[id] = Entry(image: image, capturedAt: capturedAt)
+ }
+
+ public func remove(_ id: String) {
+ entries[id] = nil
+ }
+
+ /// Forgets the Spaces not in `ids` (deleted or forgotten).
+ public func retain(_ ids: Set<String>) {
+ for id in entries.keys where !ids.contains(id) { entries[id] = nil }
+ }
+
+ /// Asks the SDK for the Space's thumbnail no older than `maxAge`
+ /// (seconds; nil: any age) and keeps it. Returns the latest image.
+ @discardableResult
+ public func refresh(_ id: String, maxAge: TimeInterval?) async -> NSImage? {
+ guard let fetch, !inFlight.contains(id) else { return self[id] }
+ inFlight.insert(id)
+ defer { inFlight.remove(id) }
+ let ms = maxAge.map { UInt64(max(0, $0) * 1000) }
+ if let data = await fetch(id, ms), let image = NSImage(data: data.image) {
+ set(id, image, at: data.capturedAt)
+ }
+ return self[id]
+ }
+
+ /// Fills each Space in `ids` that has no image yet from the daemon's
+ /// cache (any age).
+ public func warm(_ ids: [String]) async {
+ let missing = ids.filter { entries[$0] == nil && !warmed.contains($0) }
+ warmed.formUnion(missing)
+ await withTaskGroup(of: Void.self) { group in
+ for id in missing {
+ group.addTask { @MainActor in _ = await self.refresh(id, maxAge: nil) }
+ }
+ }
+ }
+
+ /// While the app runs: every running Space (as `running` lists them)
+ /// gets an image no older than the policy's background interval, every
+ /// interval, skipped while the app is hidden or in Low Power Mode.
+ public func keepFresh(running: @escaping @MainActor () -> [String],
+ active: @escaping @MainActor () -> Bool = SpaceThumbnails.appActive) {
+ keeping?.cancel()
+ let interval = TimeInterval(Self.policy.backgroundIntervalMs) / 1000
+ keeping = Task { @MainActor [weak self] in
+ while !Task.isCancelled {
+ if let self, active() {
+ for id in running() {
+ _ = await self.refresh(id, maxAge: interval)
+ }
+ }
+ try? await Task.sleep(for: .seconds(interval))
+ }
+ }
+ }
+
+ /// Visible and not saving power.
+ public static func appActive() -> Bool {
+ !NSApp.isHidden && !ProcessInfo.processInfo.isLowPowerModeEnabled
+ }
+
+ /// The last frame of a stream as an image (it is newer than any
+ /// thumbnail when the stream stops).
+ public static func image(_ buffer: CVPixelBuffer) -> NSImage? {
+ let ci = CIImage(cvPixelBuffer: buffer)
+ guard let cg = CIContext().createCGImage(ci, from: ci.extent) else { return nil }
+ return NSImage(cgImage: cg, size: NSSize(width: cg.width, height: cg.height))
+ }
+}
diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/SpacesBackend.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/SpacesBackend.swift
index 00c37f3abc..cb9286460b 100644
--- a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/SpacesBackend.swift
+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/SpacesBackend.swift
@@ -61,9 +61,11 @@ public protocol SpacesBackend: AnyObject, Sendable {
/// The Space's coding-agent runs as rows (the app core's mapping of the
/// SDK's run records, attention first).
func agentRuns(id: String) async throws -> [AppSpaceAgentRun]
- /// A small screenshot of the Space's display (JPEG or PNG bytes), for
- /// its notch tile; `nil` when the Space cannot capture.
- func thumbnail(id: String, maxDimension: UInt32) async -> Data?
+ /// The Space's latest thumbnail from the SDK's shared cache (the cua
+ /// daemon's): no older than `maxAgeMs` (nil: any age), captured fresh
+ /// when the cache is older; `nil` when there is none and the Space
+ /// cannot capture.
+ func thumbnail(id: String, maxAgeMs: UInt64?) async -> SpaceThumbnailData?
/// Icons the Space's desktop shows for many apps, in order (the SDK's
/// `Space.appIcons`, through its one icon cache): 64 px PNG or SVG
/// bytes, `nil` where the Space has none.
@@ -81,7 +83,7 @@ public protocol SpacesBackend: AnyObject, Sendable {
}
public extension SpacesBackend {
- func thumbnail(id: String, maxDimension: UInt32) async -> Data? { nil }
+ func thumbnail(id: String, maxAgeMs: UInt64?) async -> SpaceThumbnailData? { nil }
func appIcons(id: String, requests: [SpaceAppIconRequest]) async -> [Data?] { requests.map { _ in nil } }
func primaryDisplay(id: String) async -> AppStreamDisplay? { nil }
func usage(id: String) async -> AppSpaceUsage? { nil }
@@ -328,12 +330,13 @@ public final class LiveSpacesBackend: SpacesBackend, @unchecked Sendable {
return appAgentRows(runsJson: runs.map(\.json))
}
- public func thumbnail(id: String, maxDimension: UInt32) async -> Data? {
+ public func thumbnail(id: String, maxAgeMs: UInt64?) async -> SpaceThumbnailData? {
let result = await withTimeout(seconds: 5) { [cua] in
- try await cua.spaces().space(space: id).screenshot(options: ScreenshotOptions(
- format: .jpeg, quality: 70, maxDimension: maxDimension))
+ try await cua.spaces().space(space: id).thumbnail(maxAgeMs: maxAgeMs)
}
- return try? result.get().image
+ guard let t = try? result.get() else { return nil }
+ return SpaceThumbnailData(image: t.image,
+ capturedAt: Date(timeIntervalSince1970: TimeInterval(t.capturedAtMs) / 1000))
}
public func appIcons(id: String, requests: [SpaceAppIconRequest]) async -> [Data?] {
diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/CuaSpacesMacApp.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/CuaSpacesMacApp.swift
index 6e9f20726d..a394130916 100644
--- a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/CuaSpacesMacApp.swift
+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/CuaSpacesMacApp.swift
@@ -229,10 +229,14 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
}
// "Spaces tab in the notch": applied now and on every change.
Self.followNotchSetting(model, controller)
- let backend = model.backend
- controller.thumbnail = { id in
- await backend.thumbnail(id: id, maxDimension: 320).flatMap(NSImage.init(data:))
- }
+ // The tiles read the shared thumbnail store (the SDK's cache);
+ // open, every tile asks for one no older than the open interval.
+ let thumbnails = model.thumbnails
+ let openAge = TimeInterval(SpaceThumbnails.policy.openIntervalMs) / 1000
+ controller.thumbnail = { id in await thumbnails.refresh(id, maxAge: openAge) }
+ // Closed too: running Spaces' thumbnails stay a minute or two old
+ // (paused while the app is hidden or in Low Power Mode).
+ thumbnails.keepFresh(running: { model.streamableSpaceIds })
if let live = model.backend as? LiveSpacesBackend {
let teleport = live.cua.teleport()
model.notch.capture = { id in
diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/DesktopCover.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/DesktopCover.swift
new file mode 100644
index 0000000000..f938316564
--- /dev/null
+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/DesktopCover.swift
@@ -0,0 +1,145 @@
+// SPDX-License-Identifier: FSL-1.1-MIT
+// Copyright (c) 2026 Cua AI, Inc.
+
+import AppKit
+import CoreImage
+import CuaSpacesFFI
+import CuaSpacesStreaming
+import SwiftUI
+
+/// What the preview card shows over (or instead of) a Space's live desktop
+/// (the core's `appDesktopCover`): the Space's latest thumbnail, strongly
+/// blurred and slightly dimmed, with "Connecting…", a Connect button or the
+/// Space's own line centered on it. With no thumbnail yet: plain black
+/// while connecting (or waiting for Connect), the card's quiet fill for a
+/// Space that cannot stream.
+struct DesktopCoverView: View {
+ let cover: AppDesktopCover
+ /// The Space's latest thumbnail (`SpaceThumbnails`), if any.
+ let image: NSImage?
+ /// While it is created: overall progress in thousandths (the ring).
+ var progress: UInt32?
+ /// Under the line while it downloads.
+ var progressText: String?
+ var onButton: () -> Void = {}
+ @Environment(\.colorScheme) private var colorScheme
+
+ /// Blur radius as a share of the image's long edge (strong: shapes
+ /// and colors only, no text).
+ static let blurShare: CGFloat = 0.035
+ static let dim = 0.28
+ private static let blurs = NSCache<NSImage, NSImage>()
+ private static let context = CIContext()
+
+ /// The image blurred once (Core Image, edges clamped so they stay
+ /// opaque), cached per image.
+ static func blurred(_ image: NSImage) -> NSImage {
+ if let done = blurs.object(forKey: image) { return done }
+ guard let cg = image.cgImage(forProposedRect: nil, context: nil, hints: nil) else { return image }
+ let input = CIImage(cgImage: cg)
+ let radius = max(input.extent.width, input.extent.height) * blurShare
+ guard let output = input.clampedToExtent()
+ .applyingGaussianBlur(sigma: radius)
+ .cropped(to: input.extent) as CIImage?,
+ let out = context.createCGImage(output, from: input.extent) else { return image }
+ let result = NSImage(cgImage: out, size: image.size)
+ blurs.setObject(result, forKey: image)
+ return result
+ }
+
+ /// On the blurred image or on black, text and buttons draw for a dark
+ /// background.
+ private var onDark: Bool { image != nil || cover.kind != .status }
+
+ var body: some View {
+ ZStack {
+ background
+ content
+ .padding(16)
+ .environment(\.colorScheme, onDark ? .dark : colorScheme)
+ }
+ .clipped()
+ .accessibilityElement(children: .contain)
+ .accessibilityIdentifier("space-cover-\(String(describing: cover.kind))")
+ }
+
+ @ViewBuilder private var background: some View {
+ if let image {
+ Color.black
+ .overlay {
+ Image(nsImage: Self.blurred(image))
+ .resizable()
+ .interpolation(.medium)
+ .aspectRatio(contentMode: .fill)
+ }
+ .overlay(Color.black.opacity(Self.dim))
+ .accessibilityHidden(true)
+ } else if cover.kind == .status {
+ Rectangle().fill(.quaternary)
+ } else {
+ Color.black
+ }
+ }
+
+ private var content: some View {
+ VStack(spacing: 12) {
+ if cover.text != nil || progress != nil {
+ HStack(spacing: 8) {
+ if let progress { ProgressRing(permille: progress, size: 16) }
+ if let text = cover.text {
+ Text(text)
+ .font(cover.kind == .status ? .body : .title3)
+ .foregroundStyle(.secondary)
+ .multilineTextAlignment(.center)
+ .accessibilityIdentifier("space-cover-text")
+ }
+ }
+ }
+ // While it downloads: "4.2 of 23.9 GB · 85 MB/s · about 4 min".
+ if let progressText {
+ Text(progressText)
+ .font(.callout.monospacedDigit())
+ .foregroundStyle(.tertiary)
+ .lineLimit(1)
+ .accessibilityIdentifier("space-progress-text")
+ }
+ if let button = cover.button {
+ Button(button, action: onButton)
+ .buttonStyle(.borderedProminent)
+ .controlSize(cover.kind == .connect ? .large : .regular)
+ .help(cover.buttonHelp ?? "")
+ .accessibilityIdentifier(cover.kind == .connect ? "space-connect" : "space-retry")
+ }
+ }
+ }
+}
+
+/// Reads a stream session's phase for the core's cover: none without a
+/// session, and "connecting" until the first frame arrives (the transport
+/// says streaming as soon as it opens).
+struct StreamPhaseReader<Content: View>: View {
+ var session: LiveStreamSession?
+ @ViewBuilder var content: (AppStreamPhase) -> Content
+
+ var body: some View {
+ if let session { Observed(session: session, content: content) } else { content(.noSession) }
+ }
+
+ static func phase(_ status: LiveStreamSession.Status, hasFrame: Bool) -> AppStreamPhase {
+ switch status {
+ case .idle: return .idle
+ case .connecting: return .connecting
+ case .streaming: return hasFrame ? .streaming : .connecting
+ case .suspended: return .suspended
+ case .failed: return .failed
+ }
+ }
+
+ private struct Observed: View {
+ @ObservedObject var session: LiveStreamSession
+ let content: (AppStreamPhase) -> Content
+ var body: some View {
+ content(StreamPhaseReader.phase(session.status, hasFrame: session.frame != nil))
+ }
+ }
+}
diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/SpaceDetailView.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/SpaceDetailView.swift
index f43e883dfa..e13500fc4e 100644
--- a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/SpaceDetailView.swift
+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/SpaceDetailView.swift
@@ -23,6 +23,9 @@ struct SpaceDetailView: View {
@State private var dropStatus: TeleportDropZone.Status?
@State private var agents: AgentRunsModel?
@State private var sharing: ShareModel?
+ /// Connect (or Try again) was pressed: the stream opens even with
+ /// "Connect to the desktop automatically" off.
+ @State private var connectRequested = false
@Environment(\.openWindow) private var openWindow
private let copy = appSpaceDetailCopy()
@@ -78,7 +81,15 @@ struct SpaceDetailView: View {
.toolbar { toolbar(detail) }
// A delete stops the stream, its pop-outs and the polling at once
// (and a failed one starts them again).
- .task(id: live) { await connect(detail) }
+ .task(id: "\(live) \(connectRequested)") { await connect(detail) }
+ // The cover's preview: the shared store's image at once, then one
+ // no older than the background interval.
+ .task(id: live) {
+ guard detail.canStream else { return }
+ await model.thumbnails.refresh(space.id, maxAge: TimeInterval(SpaceThumbnails.policy.backgroundIntervalMs) / 1000)
+ }
+ // Leaving: the last frame is the newest preview there is.
+ .onDisappear { keepLastFrame() }
.onChange(of: deleting) { _, now in if now { disconnect() } }
.onChange(of: off) { _, now in if now { disconnect() } }
.task(id: live) {
@@ -135,42 +146,55 @@ struct SpaceDetailView: View {
}
@ViewBuilder private func preview(_ detail: AppSpaceDetail) -> some View {
- if let session, detail.canStream {
- SpaceScreenView(session: session, isInteractive: true, showsControls: false)
- } else {
+ if let notice = detail.creditNotice, !detail.canStream {
ZStack {
Rectangle().fill(.quaternary)
- if let notice = detail.creditNotice {
- // Out of Cua Cloud credit: one line and Add credit (the
- // website billing page). Local Spaces never see this.
- HStack(spacing: 12) {
- Text(notice.text).foregroundStyle(.secondary)
- Button(notice.button) { model.openBillingPage(notice.url) }
- .buttonStyle(.borderedProminent)
- .accessibilityIdentifier("add-credit")
+ // Out of Cua Cloud credit: one line and Add credit (the
+ // website billing page). Local Spaces never see this.
+ HStack(spacing: 12) {
+ Text(notice.text).foregroundStyle(.secondary)
+ Button(notice.button) { model.openBillingPage(notice.url) }
+ .buttonStyle(.borderedProminent)
+ .accessibilityIdentifier("add-credit")
+ }
+ }
+ } else {
+ StreamPhaseReader(session: detail.canStream ? session : nil) { phase in
+ let cover = model.cover(detail, requested: connectRequested, stream: phase)
+ ZStack {
+ if let session, detail.canStream {
+ SpaceScreenView(session: session, isInteractive: true, showsControls: false)
}
- } else {
- VStack(spacing: 6) {
- HStack(spacing: 8) {
- if let progress = detail.progress {
- ProgressRing(permille: progress, size: 16)
- }
- Text(detail.previewText).foregroundStyle(.secondary)
- }
- // While it downloads: "4.2 of 23.9 GB · 85 MB/s · about 4 min".
- if let text = detail.progressText {
- Text(text)
- .font(.callout.monospacedDigit())
- .foregroundStyle(.tertiary)
- .lineLimit(1)
- .accessibilityIdentifier("space-progress-text")
+ if cover.kind != .stream {
+ DesktopCoverView(cover: cover, image: model.thumbnails[space.id],
+ progress: detail.progress, progressText: detail.progressText) {
+ press(cover)
}
+ .transition(.opacity)
}
}
+ .animation(.easeOut(duration: 0.25), value: cover.kind)
}
}
}
+ /// The cover's button: Connect opens the stream; Try again starts the
+ /// failed one again.
+ private func press(_ cover: AppDesktopCover) {
+ connectRequested = true
+ guard cover.kind == .status, let session else { return }
+ Task {
+ await session.stop()
+ await session.start()
+ }
+ }
+
+ /// Keeps the stream's last frame as the Space's preview.
+ private func keepLastFrame() {
+ guard let frame = session?.frame, let image = SpaceThumbnails.image(frame) else { return }
+ model.thumbnails.set(space.id, image)
+ }
+
@ViewBuilder private var streamRows: some View {
if let session, let pips, let streams {
StreamRows(model: streams, session: session, pips: pips)
@@ -276,7 +300,9 @@ struct SpaceDetailView: View {
}
private func connect(_ detail: AppSpaceDetail) async {
- guard detail.canStream, session == nil else { return }
+ // The core decides: auto-connect on, or Connect pressed.
+ guard session == nil,
+ model.cover(detail, requested: connectRequested, stream: .noSession).openStream else { return }
do {
let provider = try await model.backend.streamProvider(id: space.id)
self.provider = provider
@@ -298,6 +324,8 @@ struct SpaceDetailView: View {
/// Stops the live desktop, closes its picture-in-picture panels and
/// forgets the window list (the Space is being deleted).
private func disconnect() {
+ keepLastFrame()
+ connectRequested = false
agents = nil
pips?.popInAll()
if let session { Task { await session.stop() } }
@@ -555,12 +583,29 @@ struct SpaceWindowView: View {
var body: some View {
let space = model.spaces.first { $0.id == spaceId }
Group {
- if let session {
- SpaceScreenView(session: session, isInteractive: true, showsControls: true)
- } else {
+ if let error {
ZStack {
Rectangle().fill(.quaternary)
- Text(error ?? space.map { model.detail($0).previewText } ?? "").foregroundStyle(.secondary)
+ Text(error).foregroundStyle(.secondary)
+ }
+ } else if let space {
+ // Open is a request to connect: the same cover as the
+ // detail's until the first frame.
+ StreamPhaseReader(session: session) { phase in
+ let cover = model.cover(model.detail(space), requested: true, stream: phase)
+ ZStack {
+ if let session { SpaceScreenView(session: session, isInteractive: true, showsControls: true) }
+ if cover.kind != .stream {
+ DesktopCoverView(cover: cover, image: model.thumbnails[spaceId]) {
+ // Try again.
+ guard let session else { return }
+ Task {
+ await session.stop()
+ await session.start()
+ }
+ }
+ }
+ }
}
}
}
diff --git a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/DesktopCoverTests.swift b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/DesktopCoverTests.swift
new file mode 100644
index 0000000000..b042d698eb
--- /dev/null
+++ b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/DesktopCoverTests.swift
@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: FSL-1.1-MIT
+// Copyright (c) 2026 Cua AI, Inc.
+
+import AppKit
+import CuaSpacesFFI
+@testable import CuaSpacesMacKit
+import Foundation
+import SwiftUI
+import Testing
+
+/// The preview cover's state (the core's), the auto-connect setting and the
+/// one thumbnail store the notch tiles and the cover share.
+@MainActor
+@Suite("Desktop cover")
+struct DesktopCoverTests {
+ init() { _ = NSApplication.shared }
+
+ func runningDetail(_ model: AppModel) async throws -> AppSpaceDetail {
+ await model.refresh()
+ let space = try #require(model.spaces.first { model.detail($0).canStream })
+ return model.detail(space)
+ }
+
+ @Test func autoConnectIsOnByDefaultAndTheCoverSaysConnecting() async throws {
+ let model = ViewModelTests().makeModel()
+ #expect(model.settings.autoConnect)
+ let detail = try await runningDetail(model)
+ let cover = model.cover(detail, requested: false, stream: .noSession)
+ #expect(cover.kind == .connecting && cover.text == "Connecting\u{2026}" && cover.openStream)
+ #expect(model.cover(detail, requested: false, stream: .streaming).kind == .stream)
+ }
+
+ @Test func turnedOffTheCoverWaitsForConnect() async throws {
+ let model = ViewModelTests().makeModel()
+ await model.loadSettings()
+ let general = try #require(model.settingsPage.sections.first { $0.id == "general" })
+ let row = try #require(general.rows.first { $0.id == "auto-connect" })
+ #expect(row.kind == .toggle && row.label == "Connect to the desktop automatically")
+ #expect(row.options.first { $0.id == "on" }?.active == true)
+ await model.choose(row: "auto-connect", option: "off")
+ #expect(!model.settings.autoConnect)
+ // Saved: a new model on the same file reads it back.
+ #expect(!appSettingsLoad(path: model.settingsPath).autoConnect)
+ let detail = try await runningDetail(model)
+ let cover = model.cover(detail, requested: false, stream: .noSession)
+ #expect(cover.kind == .connect && cover.button == "Connect" && !cover.openStream)
+ // Pressed: open, connecting, then live.
+ let pressed = model.cover(detail, requested: true, stream: .noSession)
+ #expect(pressed.kind == .connecting && pressed.openStream)
+ #expect(model.cover(detail, requested: true, stream: .streaming).kind == .stream)
+ }
+
+ /// The transport says streaming as soon as it opens: until a frame
+ /// arrives, the cover still says Connecting.
+ @Test func connectingLastsUntilTheFirstFrame() {
+ typealias R = StreamPhaseReader<EmptyView>
+ #expect(R.phase(.streaming, hasFrame: false) == .connecting)
+ #expect(R.phase(.streaming, hasFrame: true) == .streaming)
+ #expect(R.phase(.idle, hasFrame: false) == .idle)
+ #expect(R.phase(.failed("x"), hasFrame: false) == .failed)
+ }
+
+ @Test func theNotchAndTheCoverReadOneEntry() async throws {
+ let model = ViewModelTests().makeModel()
+ #expect(model.thumbnails === model.notch.thumbnails)
+ let image = DesktopCoverTests.desktop()
+ var asked: [(String, UInt64?)] = []
+ model.thumbnails.fetch = { id, maxAge in
+ asked.append((id, maxAge))
+ return SpaceThumbnailData(image: image.tiffRepresentation!, capturedAt: Date())
+ }
+ // The notch's refresh fills the entry the cover reads.
+ let notchImage = await model.thumbnails.refresh("local:aurora", maxAge: 3)
+ #expect(notchImage != nil)
+ #expect(model.notch.thumbnails["local:aurora"] === model.thumbnails["local:aurora"])
+ #expect(asked.count == 1 && asked[0].0 == "local:aurora" && asked[0].1 == 3_000)
+ }
+
+ @Test func theStoreKeepsTheNewestAndForgetsGoneSpaces() async {
+ let store = SpaceThumbnails()
+ let a = DesktopCoverTests.desktop(), b = DesktopCoverTests.desktop()
+ let now = Date()
+ store.set("s1", a, at: now)
+ // An older capture never replaces a newer one (a stream's last
+ // frame is newer than the daemon's cache).
+ store.set("s1", b, at: now.addingTimeInterval(-60))
+ #expect(store["s1"] === a)
+ store.set("s1", b, at: now.addingTimeInterval(1))
+ #expect(store["s1"] === b)
+ store.set("s2", a)
+ store.retain(["s2"])
+ #expect(store["s1"] == nil && store["s2"] != nil)
+ store["s2"] = nil
+ #expect(store.entries.isEmpty)
+ }
+
+ @Test func warmingAsksTheCacheOncePerSpace() async {
+ let store = SpaceThumbnails()
+ var asked: [UInt64?] = []
+ store.fetch = { _, maxAge in
+ asked.append(maxAge)
+ return nil
+ }
+ await store.warm(["s1"])
+ await store.warm(["s1"])
+ #expect(asked.count == 1, "once per launch")
+ #expect(asked == [nil], "any age: the daemon's cache answers at once")
+ }
+
+ @Test func thePolicyComesFromTheCore() {
+ let p = SpaceThumbnails.policy
+ #expect((60_000...120_000).contains(p.backgroundIntervalMs))
+ #expect(p.openIntervalMs == 3_000)
+ }
+
+ /// A stand-in desktop for the preview: a wallpaper gradient, a menu bar
+ /// and two windows.
+ static func desktop(size: NSSize = NSSize(width: 640, height: 400)) -> NSImage {
+ NSImage(size: size, flipped: false) { rect in
+ NSGradient(colors: [NSColor(calibratedRed: 0.16, green: 0.33, blue: 0.62, alpha: 1),
+ NSColor(calibratedRed: 0.86, green: 0.47, blue: 0.36, alpha: 1)])?
+ .draw(in: rect, angle: -60)
+ NSColor(white: 0.97, alpha: 0.9).setFill()
+ NSRect(x: 0, y: rect.height - 16, width: rect.width, height: 16).fill()
+ for (frame, tone) in [(NSRect(x: 60, y: 90, width: 300, height: 220), 0.98),
+ (NSRect(x: 300, y: 50, width: 260, height: 180), 0.2)] {
+ NSColor(white: tone, alpha: 1).setFill()
+ NSBezierPath(roundedRect: frame, xRadius: 8, yRadius: 8).fill()
+ }
+ return true
+ }
+ }
+}
diff --git a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/SnapshotTests.swift b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/SnapshotTests.swift
index 66e0527260..014e310c02 100644
--- a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/SnapshotTests.swift
+++ b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/SnapshotTests.swift
@@ -190,6 +190,49 @@ struct SnapshotTests {
try assertSnapshot(view, "space-preview", size: CGSize(width: 520, height: 480))
}
+ /// The preview card while the stream opens and while it waits for
+ /// Connect: the Space's thumbnail blurred and dimmed with the core's
+ /// words centered, or plain black when there is no thumbnail yet.
+ @Test func desktopCover() async throws {
+ let m = try await model()
+ let space = try #require(m.spaces.first { m.detail($0).canStream })
+ let detail = m.detail(space)
+ let preview = DesktopCoverTests.desktop()
+ func card(_ cover: AppDesktopCover, _ image: NSImage?) -> some View {
+ Form {
+ Section {
+ PreviewCard(session: nil) { DesktopCoverView(cover: cover, image: image) }
+ }
+ }
+ .formStyle(.grouped)
+ }
+ let size = CGSize(width: 520, height: 360)
+ let connecting = m.cover(detail, requested: false, stream: .noSession)
+ #expect(connecting.kind == .connecting)
+ try assertSnapshot(card(connecting, preview), "space-cover-connecting", size: size)
+ try assertSnapshot(card(connecting, nil), "space-cover-connecting-black", size: size)
+ await m.choose(row: "auto-connect", option: "off")
+ let manual = m.cover(detail, requested: false, stream: .noSession)
+ #expect(manual.kind == .connect)
+ try assertSnapshot(card(manual, preview), "space-cover-connect", size: size)
+ try assertSnapshot(card(manual, nil), "space-cover-connect-black", size: size)
+ // A Space that cannot stream: its line on the same blurred preview.
+ let stopped = appDesktopCover(input: AppDesktopCoverInput(
+ canStream: false, previewText: "Stopped", autoConnect: true, connectRequested: false,
+ stream: .noSession))
+ try assertSnapshot(card(stopped, preview), "space-cover-stopped", size: size)
+ }
+
+ /// Settings, General: "Connect to the desktop automatically", on by
+ /// default (the `settings` reference), then off.
+ @Test func settingsAutoConnectOff() async throws {
+ let m = try await model()
+ m.settings.experiments.cuaVolume = true
+ await m.choose(row: "auto-connect", option: "off")
+ await m.loadSettings()
+ try assertSnapshot(SettingsView(model: m), "settings-auto-connect-off", size: CGSize(width: 520, height: 640))
+ }
+
/// "Teleport an app…" as the core's grid: sections, a tile previewing
/// its app's frontmost window, icons, the app that cannot move dimmed.
@Test func teleportPickerGrid() async throws {
diff --git a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/settings-auto-connect-off.png b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/settings-auto-connect-off.png
new file mode 100644
index 0000000000..272bc70ab4
Binary files /dev/null and b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/settings-auto-connect-off.png differ
diff --git a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/settings-keyvault.png b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/settings-keyvault.png
index b143a9da56..7cf1f00252 100644
Binary files a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/settings-keyvault.png and b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/settings-keyvault.png differ
diff --git a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/settings-login-approval.png b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/settings-login-approval.png
index e3b8cea5ab..7f6e0123b6 100644
Binary files a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/settings-login-approval.png and b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/settings-login-approval.png differ
diff --git a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/settings-storage.png b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/settings-storage.png
index bbd9a1782b..b7494b42dd 100644
Binary files a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/settings-storage.png and b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/settings-storage.png differ
diff --git a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/settings.png b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/settings.png
index dbbd3bb1cc..c970e30e0b 100644
Binary files a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/settings.png and b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/settings.png differ
diff --git a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/space-cover-connect-black.png b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/space-cover-connect-black.png
new file mode 100644
index 0000000000..e82c8dfbef
Binary files /dev/null and b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/space-cover-connect-black.png differ
diff --git a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/space-cover-connect.png b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/space-cover-connect.png
new file mode 100644
index 0000000000..ff72039e1b
Binary files /dev/null and b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/space-cover-connect.png differ
diff --git a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/space-cover-connecting-black.png b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/space-cover-connecting-black.png
new file mode 100644
index 0000000000..ecc323064f
Binary files /dev/null and b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/space-cover-connecting-black.png differ
diff --git a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/space-cover-connecting.png b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/space-cover-connecting.png
new file mode 100644
index 0000000000..1d0802be17
Binary files /dev/null and b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/space-cover-connecting.png differ
diff --git a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/space-cover-stopped.png b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/space-cover-stopped.png
new file mode 100644
index 0000000000..2e972c4c85
Binary files /dev/null and b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/Snapshots/space-cover-stopped.png differ
diff --git a/docs/content/docs/cua-sdk/guides/meta.json b/docs/content/docs/cua-sdk/guides/meta.json
index 0c57a8415d..df88ca9b91 100644
--- a/docs/content/docs/cua-sdk/guides/meta.json
+++ b/docs/content/docs/cua-sdk/guides/meta.json
@@ -7,6 +7,7 @@
"sidecars",
"lifecycle",
"desktop",
+ "thumbnails",
"spacesd",
"local-runtimes",
"disk-usage",
diff --git a/docs/content/docs/cua-sdk/guides/thumbnails.mdx b/docs/content/docs/cua-sdk/guides/thumbnails.mdx
new file mode 100644
index 0000000000..d62c8a50a2
--- /dev/null
+++ b/docs/content/docs/cua-sdk/guides/thumbnails.mdx
@@ -0,0 +1,59 @@
+---
+title: Space thumbnails
+description: Read a Space's latest small preview from the cache every client on the machine shares.
+---
+
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+
+For a small preview of a Space (a tile, a list row, a placeholder while a
+stream connects), use `Space.thumbnail` rather than `screenshot`. It reads one
+cache that every client on the machine shares (the Spaces app, the CLI, your
+scripts): a small JPEG of the primary display and when it was captured. The
+cached image comes back at once when it is younger than `max_age_ms`; otherwise
+the SDK captures a fresh one through cua-spacesd and keeps it for the next
+caller. When that capture fails, the older image comes back, and
+`captured_at_ms` says how old it is.
+
+<Tabs groupId="language" persist items={['Python', 'TypeScript', 'Swift']}>
+ <Tab value="Python">
+
+```python skip="no-runner"
+import cua
+
+space = await cua.connect().spaces().space("local:dev")
+thumb = await space.thumbnail(max_age_ms=120_000) # None: any age
+print(thumb.width, thumb.height, thumb.captured_at_ms)
+```
+
+ </Tab>
+ <Tab value="TypeScript">
+
+```ts skip="no-runner"
+import { connect } from '@trycua/cua';
+
+const space = await connect().spaces().space('local:dev');
+const thumb = await space.thumbnail(120_000n); // undefined: any age
+console.log(thumb.width, thumb.height, thumb.capturedAtMs);
+```
+
+ </Tab>
+ <Tab value="Swift">
+
+```swift skip="no-runner"
+import Cua
+
+let space = try await Cua.connect(address: nil, token: nil).spaces().space(space: "local:dev")
+let thumb = try await space.thumbnail(maxAgeMs: 120_000) // nil: any age
+print(thumb.width, thumb.height, thumb.capturedAtMs)
+```
+
+ </Tab>
+</Tabs>
+
+The cua daemon owns the cache under `~/.cua/cache/thumbnails`. It keeps the
+latest image per Space across restarts, drops a Space's image when the Space is
+deleted or removed, and caps the cache at 32 MB (the oldest images go first).
+While any client has asked for a thumbnail in the last 10 minutes, the daemon
+also captures a new one for each running Space about every 90 seconds, so a
+preview is seldom more than a couple of minutes old. When nobody asks, it
+captures nothing and puts no load on the guests.
diff --git a/docs/content/docs/cua-sdk/reference/index.mdx b/docs/content/docs/cua-sdk/reference/index.mdx
index 9ce112cb3d..2007e3dc7b 100644
--- a/docs/content/docs/cua-sdk/reference/index.mdx
+++ b/docs/content/docs/cua-sdk/reference/index.mdx
@@ -135,6 +135,6 @@ Pages marked *Cua Spaces app export* document the APIs the Cua Spaces apps are b
| --- | --- |
| [Protocol](/cua-sdk/reference/protocol) | The gRPC contracts of cua-spacesd (`cua.env.v1`) and the cua daemon (`cua.daemon.v1`). |
-289 items, 378 methods. The [Types](/cua-sdk/reference/types) page lists them.
+290 items, 379 methods. The [Types](/cua-sdk/reference/types) page lists them.
-The Cua Spaces app export adds 678 items and 36 methods.
+The Cua Spaces app export adds 685 items and 36 methods.
diff --git a/docs/content/docs/cua-sdk/reference/protocol/daemon-spaces.mdx b/docs/content/docs/cua-sdk/reference/protocol/daemon-spaces.mdx
index 8859101645..1a6c40314a 100644
--- a/docs/content/docs/cua-sdk/reference/protocol/daemon-spaces.mdx
+++ b/docs/content/docs/cua-sdk/reference/protocol/daemon-spaces.mdx
@@ -47,6 +47,7 @@ without touching it.
| [`ListSpaceTools`](#spaceservicelistspacetools) | [`ListSpaceToolsRequest`](#listspacetoolsrequest) | [`ListSpaceToolsResponse`](#listspacetoolsresponse) | unary |
| [`CallSpaceTool`](#spaceservicecallspacetool) | [`CallSpaceToolRequest`](#callspacetoolrequest) | [`CallSpaceToolResponse`](#callspacetoolresponse) | unary |
| [`ListHosts`](#spaceservicelisthosts) | [`ListHostsRequest`](#listhostsrequest) | [`ListHostsResponse`](#listhostsresponse) | unary |
+| [`GetSpaceThumbnail`](#spaceservicegetspacethumbnail) | [`GetSpaceThumbnailRequest`](#getspacethumbnailrequest) | [`GetSpaceThumbnailResponse`](#getspacethumbnailresponse) | unary |
### SpaceService.AddSpace
@@ -176,6 +177,17 @@ limits: what `CreateSpace` takes as `on="host:<id>"` (the New Space
wizard's Run on menu). One that does not answer is listed offline when
it provided a Space before.
+### SpaceService.GetSpaceThumbnail
+
+`/cua.daemon.v1.SpaceService/GetSpaceThumbnail`, unary: [`GetSpaceThumbnailRequest`](#getspacethumbnailrequest) to [`GetSpaceThumbnailResponse`](#getspacethumbnailresponse).
+
+The Space's latest thumbnail (a small JPEG of its primary display)
+from the daemon's cache, which every client on this machine shares:
+the cached image when it is younger than `max_age`, else a fresh
+capture through cua-spacesd (the cached one again, with its older
+`captured_at`, when the capture fails). Asking keeps the daemon
+refreshing running Spaces' thumbnails in the background for a while.
+
## Types in `cua/daemon/v1/spaces.proto`
### Space
@@ -574,3 +586,24 @@ Response for `SpaceService.ListHosts`.
| Field | # | Type | Description |
| --- | --- | --- | --- |
| `hosts` | 1 | repeated [`SpacesHost`](#spaceshost) | In order: relay hosts, then direct ones. |
+
+### GetSpaceThumbnailRequest
+
+Request for `SpaceService.GetSpaceThumbnail`.
+
+| Field | # | Type | Description |
+| --- | --- | --- | --- |
+| `space` | 1 | `string` | Space. |
+| `max_age` | 2 | `google.protobuf.Duration` | How old a cached thumbnail may be (unset: any age; zero: always capture). |
+
+### GetSpaceThumbnailResponse
+
+Response for `SpaceService.GetSpaceThumbnail`.
+
+| Field | # | Type | Description |
+| --- | --- | --- | --- |
+| `image` | 1 | `bytes` | Encoded image. |
+| `format` | 2 | `string` | "jpeg". |
+| `width` | 3 | `uint32` | Pixel width. |
+| `height` | 4 | `uint32` | Pixel height. |
+| `captured_at` | 5 | `google.protobuf.Timestamp` | When it was captured. |
diff --git a/docs/content/docs/cua-sdk/reference/protocol/index.mdx b/docs/content/docs/cua-sdk/reference/protocol/index.mdx
index 8f8658cadc..6cff78e2da 100644
--- a/docs/content/docs/cua-sdk/reference/protocol/index.mdx
+++ b/docs/content/docs/cua-sdk/reference/protocol/index.mdx
@@ -53,7 +53,7 @@ Tickets go in `?ticket=` or the WebSocket subprotocol `cua.ticket.<ticket>`. Tic
| [`HostSpacesService`](/cua-sdk/reference/protocol/env-host-spaces#hostspacesservice) | `cua.env.v1` | [Host Spaces](/cua-sdk/reference/protocol/env-host-spaces) | 6 |
| [`SandboxService`](/cua-sdk/reference/protocol/daemon-sandboxes#sandboxservice) | `cua.daemon.v1` | [Daemon: sandboxes](/cua-sdk/reference/protocol/daemon-sandboxes) | 19 |
| [`RuntimeService`](/cua-sdk/reference/protocol/daemon-runtimes#runtimeservice) | `cua.daemon.v1` | [Daemon: local runtimes](/cua-sdk/reference/protocol/daemon-runtimes) | 5 |
-| [`SpaceService`](/cua-sdk/reference/protocol/daemon-spaces#spaceservice) | `cua.daemon.v1` | [Daemon: Spaces](/cua-sdk/reference/protocol/daemon-spaces) | 16 |
+| [`SpaceService`](/cua-sdk/reference/protocol/daemon-spaces#spaceservice) | `cua.daemon.v1` | [Daemon: Spaces](/cua-sdk/reference/protocol/daemon-spaces) | 17 |
| [`DaemonService`](/cua-sdk/reference/protocol/daemon-service#daemonservice) | `cua.daemon.v1` | [Daemon: service](/cua-sdk/reference/protocol/daemon-service) | 3 |
## Metadata and HTTP routes
diff --git a/docs/content/docs/cua-sdk/reference/rust/cua-sdk.mdx b/docs/content/docs/cua-sdk/reference/rust/cua-sdk.mdx
index fec9b122a1..8c7d7370f4 100644
--- a/docs/content/docs/cua-sdk/reference/rust/cua-sdk.mdx
+++ b/docs/content/docs/cua-sdk/reference/rust/cua-sdk.mdx
@@ -263,6 +263,20 @@ pub struct SpacesdFeature {
}
```
+### `SpaceThumbnail`
+
+A Space's latest thumbnail, from the cache every client ...
+
+```rust
+pub struct SpaceThumbnail {
+ pub image: Vec<u8>,
+ pub format: ImageFormat,
+ pub width: u32,
+ pub height: u32,
+ pub captured_at_ms: u64,
+}
+```
+
### `TransferResult`
Result of an upload or download.
diff --git a/docs/content/docs/cua-sdk/reference/rust/cua-spaces.mdx b/docs/content/docs/cua-sdk/reference/rust/cua-spaces.mdx
index 89891e9fc3..e7d7951264 100644
--- a/docs/content/docs/cua-sdk/reference/rust/cua-spaces.mdx
+++ b/docs/content/docs/cua-sdk/reference/rust/cua-spaces.mdx
@@ -48,6 +48,7 @@ More of this crate: [client](/cua-sdk/reference/rust/cua-spaces-client), [agents
- `site_login`: The Keyvault seam and the whole `request_site_login` ...
- `stream`: Streams: targets, media tickets, and a Rust media ...
- `teleport_broker`: The Keyvault broker seam the `teleport_app` MCP tool ...
+- `thumbnails`: Space thumbnails, cached once for every client on this ...
- `volume`: A volume mounted in a Space's guest, served from this ...
- `walk`: Host-side folder walks for transfers, optionally ...
@@ -1606,6 +1607,10 @@ impl Spaces {
fn fleet_pool_name(&self, runtime: FleetRuntime, image: &str) -> String;
async fn recover_interrupted_creates(&self, budget: Duration) -> Vec<RecoveredCreate>;
async fn delete(&self, space: &str) -> Result<String>;
+ fn thumbnails(&self) -> &ThumbnailCache;
+ async fn thumbnail(&self, space: &str, max_age: Option<Duration>) -> Result<Thumbnail>;
+ async fn refresh_thumbnails(&self) -> usize;
+ fn spawn_thumbnail_refresh(&self) -> JoinHandle<()>;
fn power_of(&self, id: &str) -> (String, String);
async fn stop(&self, space: &str) -> Result<SpacePower>;
async fn start(&self, space: &str) -> Result<SpacePower>;
@@ -1931,6 +1936,44 @@ pub enum SessionDelivery {
}
```
+### `thumbnails::Thumbnail`
+
+One Space's latest thumbnail.
+
+```rust
+pub struct Thumbnail {
+ pub image: Vec<u8>,
+ pub format: String,
+ pub width: u32,
+ pub height: u32,
+ pub captured_at: SystemTime,
+}
+impl Thumbnail {
+ fn is_fresh(&self, max_age: Option<Duration>, now: SystemTime) -> bool;
+}
+```
+
+### `thumbnails::ThumbnailCache`
+
+The cache.
+
+```rust
+pub struct ThumbnailCache { /* private fields */ }
+impl ThumbnailCache {
+ fn new(dir: Option<PathBuf>, disk_bytes: u64) -> Self;
+ fn in_home(home: &Path) -> Self;
+ fn dir(&self) -> Option<&Path>;
+ fn get(&self, space: &str) -> Option<Thumbnail>;
+ fn spaces(&self) -> Vec<String>;
+ fn put(&self, space: &str, t: Thumbnail);
+ fn remove(&self, space: &str);
+ fn retain(&self, keep: &HashSet<String>);
+ fn note_interest(&self, now: Instant);
+ fn interested(&self, now: Instant) -> bool;
+ fn due(&self, space: &str, now: SystemTime) -> bool;
+}
+```
+
### `volume::VolumeAttachment`
A mounted volume in a Space.
@@ -2268,6 +2311,20 @@ pub const DELIVERY_QUEUE: usize = 256;
/// A window narrower or shorter than this ...
pub const MIN_STREAMABLE_SIDE: f64 = 40.0;
+// mod thumbnails
+/// A running Space's thumbnail is captured ...
+pub const BACKGROUND_INTERVAL: Duration = _;
+/// Disk cap for the whole cache.
+pub const DISK_BYTES: u64 = _;
+/// How long one request keeps the ...
+pub const INTEREST_WINDOW: Duration = _;
+/// Long edge of a captured thumbnail ...
+pub const MAX_DIMENSION: u32 = 320;
+/// JPEG quality of a captured thumbnail.
+pub const QUALITY: u32 = 70;
+/// How often the daemon checks which ...
+pub const REFRESH_TICK: Duration = _;
+
// mod volume
/// The guest feature.
pub const VOLUME_FEATURE: &str = "volume.mount";
diff --git a/docs/content/docs/cua-sdk/reference/spaces/app-core/index.mdx b/docs/content/docs/cua-sdk/reference/spaces/app-core/index.mdx
index a7ebf18a1d..6320ac3855 100644
--- a/docs/content/docs/cua-sdk/reference/spaces/app-core/index.mdx
+++ b/docs/content/docs/cua-sdk/reference/spaces/app-core/index.mdx
@@ -72,7 +72,7 @@ pub fn app_menu_input_from_json(json: String) -> Result<AppMenuInput, CuaError>
## All items
-561 items, across this page and its subpages, grouped by page. Methods are listed on their object.
+568 items, across this page and its subpages, grouped by page. Methods are listed on their object.
**About, updates and launch**: [`app_about_after_launch`](/cua-sdk/reference/spaces/app-core/about#app_about_after_launch), [`app_about_allowed_channels`](/cua-sdk/reference/spaces/app-core/about#app_about_allowed_channels), [`app_about_input_from_json`](/cua-sdk/reference/spaces/app-core/about#app_about_input_from_json), [`app_about_refresh_notice`](/cua-sdk/reference/spaces/app-core/about#app_about_refresh_notice), [`app_about_restart_daemon`](/cua-sdk/reference/spaces/app-core/about#app_about_restart_daemon), [`app_about_view`](/cua-sdk/reference/spaces/app-core/about#app_about_view), [`app_daemon_check_from_json`](/cua-sdk/reference/spaces/app-core/about#app_daemon_check_from_json), [`app_launch_input_from_json`](/cua-sdk/reference/spaces/app-core/about#app_launch_input_from_json), [`app_refresh_report_from_json`](/cua-sdk/reference/spaces/app-core/about#app_refresh_report_from_json), [`AppAboutInput`](/cua-sdk/reference/spaces/app-core/about#appaboutinput-record), [`AppAboutLink`](/cua-sdk/reference/spaces/app-core/about#appaboutlink-record), [`AppAboutLinkId`](/cua-sdk/reference/spaces/app-core/about#appaboutlinkid-enum), [`AppAboutUpdates`](/cua-sdk/reference/spaces/app-core/about#appaboutupdates-record), [`AppAboutView`](/cua-sdk/reference/spaces/app-core/about#appaboutview-record), [`AppCliInstaller`](/cua-sdk/reference/spaces/app-core/about#appcliinstaller), [`AppCliInstallPlan`](/cua-sdk/reference/spaces/app-core/about#appcliinstallplan-record), [`AppCliInstallRequest`](/cua-sdk/reference/spaces/app-core/about#appcliinstallrequest-record), [`AppDaemonCheck`](/cua-sdk/reference/spaces/app-core/about#appdaemoncheck-record), [`AppInstallMethod`](/cua-sdk/reference/spaces/app-core/about#appinstallmethod-enum), [`AppLaunchInput`](/cua-sdk/reference/spaces/app-core/about#applaunchinput-record), [`AppLaunchPlan`](/cua-sdk/reference/spaces/app-core/about#applaunchplan-record), [`AppRefreshReport`](/cua-sdk/reference/spaces/app-core/about#apprefreshreport-record), [`AppUpdateChannel`](/cua-sdk/reference/spaces/app-core/about#appupdatechannel-enum)
@@ -92,6 +92,8 @@ pub fn app_menu_input_from_json(json: String) -> Result<AppMenuInput, CuaError>
**Power button**: [`app_creates_is_powering`](/cua-sdk/reference/spaces/app-core/power#app_creates_is_powering), [`app_power_button`](/cua-sdk/reference/spaces/app-core/power#app_power_button), [`AppPendingPower`](/cua-sdk/reference/spaces/app-core/power#apppendingpower-record), [`AppPowerButton`](/cua-sdk/reference/spaces/app-core/power#apppowerbutton-record), [`AppPowerControl`](/cua-sdk/reference/spaces/app-core/power#apppowercontrol-enum), [`AppSpacePower`](/cua-sdk/reference/spaces/app-core/power#appspacepower-record)
+**Stream section and facts**: [`app_desktop_cover`](/cua-sdk/reference/spaces/app-core/stream#app_desktop_cover), [`app_space_detail_live`](/cua-sdk/reference/spaces/app-core/stream#app_space_detail_live), [`app_stream_desktop_row_id`](/cua-sdk/reference/spaces/app-core/stream#app_stream_desktop_row_id), [`app_stream_pip_click`](/cua-sdk/reference/spaces/app-core/stream#app_stream_pip_click), [`app_stream_pip_reduce`](/cua-sdk/reference/spaces/app-core/stream#app_stream_pip_reduce), [`app_stream_section`](/cua-sdk/reference/spaces/app-core/stream#app_stream_section), [`app_thumbnail_policy`](/cua-sdk/reference/spaces/app-core/stream#app_thumbnail_policy), [`app_usage_refresh_ms`](/cua-sdk/reference/spaces/app-core/stream#app_usage_refresh_ms), [`AppDesktopCover`](/cua-sdk/reference/spaces/app-core/stream#appdesktopcover-record), [`AppDesktopCoverInput`](/cua-sdk/reference/spaces/app-core/stream#appdesktopcoverinput-record), [`AppDesktopCoverKind`](/cua-sdk/reference/spaces/app-core/stream#appdesktopcoverkind-enum), [`AppPipCommand`](/cua-sdk/reference/spaces/app-core/stream#apppipcommand-enum), [`AppPipEvent`](/cua-sdk/reference/spaces/app-core/stream#apppipevent-enum), [`AppSpaceUsage`](/cua-sdk/reference/spaces/app-core/stream#appspaceusage-record), [`AppStreamDisplay`](/cua-sdk/reference/spaces/app-core/stream#appstreamdisplay-record), [`AppStreamPhase`](/cua-sdk/reference/spaces/app-core/stream#appstreamphase-enum), [`AppStreamRow`](/cua-sdk/reference/spaces/app-core/stream#appstreamrow-record), [`AppStreamRowAction`](/cua-sdk/reference/spaces/app-core/stream#appstreamrowaction-record), [`AppStreamRowActionId`](/cua-sdk/reference/spaces/app-core/stream#appstreamrowactionid-enum), [`AppStreamRowIcon`](/cua-sdk/reference/spaces/app-core/stream#appstreamrowicon-enum), [`AppStreamRowKind`](/cua-sdk/reference/spaces/app-core/stream#appstreamrowkind-enum), [`AppStreamSection`](/cua-sdk/reference/spaces/app-core/stream#appstreamsection-record), [`AppStreamSectionInput`](/cua-sdk/reference/spaces/app-core/stream#appstreamsectioninput-record), [`AppThumbnailPolicy`](/cua-sdk/reference/spaces/app-core/stream#appthumbnailpolicy-record)
+
**Window drag trigger**: [`app_drag_classify`](/cua-sdk/reference/spaces/app-core/drag-trigger#app_drag_classify), [`app_drag_displays`](/cua-sdk/reference/spaces/app-core/drag-trigger#app_drag_displays), [`app_drag_portal_displays`](/cua-sdk/reference/spaces/app-core/drag-trigger#app_drag_portal_displays), [`app_drag_trigger_apply`](/cua-sdk/reference/spaces/app-core/drag-trigger#app_drag_trigger_apply), [`app_drag_trigger_initial`](/cua-sdk/reference/spaces/app-core/drag-trigger#app_drag_trigger_initial), [`AppDragDisplay`](/cua-sdk/reference/spaces/app-core/drag-trigger#appdragdisplay-record), [`AppDragKind`](/cua-sdk/reference/spaces/app-core/drag-trigger#appdragkind-enum), [`AppDragTriggerEvent`](/cua-sdk/reference/spaces/app-core/drag-trigger#appdragtriggerevent-enum), [`AppDragTriggerState`](/cua-sdk/reference/spaces/app-core/drag-trigger#appdragtriggerstate-record), [`AppDragTriggerTransition`](/cua-sdk/reference/spaces/app-core/drag-trigger#appdragtriggertransition-record), [`AppStillAnchor`](/cua-sdk/reference/spaces/app-core/drag-trigger#appstillanchor-record), [`AppTriggerPhase`](/cua-sdk/reference/spaces/app-core/drag-trigger#apptriggerphase-enum)
**Onboarding and settings**: [`app_driver_preview`](/cua-sdk/reference/spaces/app-core/onboarding-settings#app_driver_preview), [`app_driver_preview_frame`](/cua-sdk/reference/spaces/app-core/onboarding-settings#app_driver_preview_frame), [`app_driver_preview_still`](/cua-sdk/reference/spaces/app-core/onboarding-settings#app_driver_preview_still), [`app_format_hotkey`](/cua-sdk/reference/spaces/app-core/onboarding-settings#app_format_hotkey), [`app_onboarding_action_from_json`](/cua-sdk/reference/spaces/app-core/onboarding-settings#app_onboarding_action_from_json), [`app_onboarding_copy`](/cua-sdk/reference/spaces/app-core/onboarding-settings#app_onboarding_copy), [`app_onboarding_initial`](/cua-sdk/reference/spaces/app-core/onboarding-settings#app_onboarding_initial), [`app_onboarding_installed_at_text`](/cua-sdk/reference/spaces/app-core/onboarding-settings#app_onboarding_installed_at_text), [`app_onboarding_reduce`](/cua-sdk/reference/spaces/app-core/onboarding-settings#app_onboarding_reduce), [`app_onboarding_replaces_text`](/cua-sdk/reference/spaces/app-core/onboarding-settings#app_onboarding_replaces_text), [`app_onboarding_sign_in_code_text`](/cua-sdk/reference/spaces/app-core/onboarding-settings#app_onboarding_sign_in_code_text), [`app_onboarding_signed_in_text`](/cua-sdk/reference/spaces/app-core/onboarding-settings#app_onboarding_signed_in_text), [`app_onboarding_view`](/cua-sdk/reference/spaces/app-core/onboarding-settings#app_onboarding_view), [`app_presentation_preview`](/cua-sdk/reference/spaces/app-core/onboarding-settings#app_presentation_preview), [`app_presentation_preview_frame`](/cua-sdk/reference/spaces/app-core/onboarding-settings#app_presentation_preview_frame), [`app_presentation_preview_still`](/cua-sdk/reference/spaces/app-core/onboarding-settings#app_presentation_preview_still), [`app_settings_load`](/cua-sdk/reference/spaces/app-core/onboarding-settings#app_settings_load), [`app_settings_save`](/cua-sdk/reference/spaces/app-core/onboarding-settings#app_settings_save), [`AppDriverFrame`](/cua-sdk/reference/spaces/app-core/onboarding-settings#appdriverframe-record), [`AppDriverPreview`](/cua-sdk/reference/spaces/app-core/onboarding-settings#appdriverpreview-record), [`AppKeyCombo`](/cua-sdk/reference/spaces/app-core/onboarding-settings#appkeycombo-record), [`AppMenuPreview`](/cua-sdk/reference/spaces/app-core/onboarding-settings#appmenupreview-record), [`AppMenuPreviewRow`](/cua-sdk/reference/spaces/app-core/onboarding-settings#appmenupreviewrow-record), [`AppModeChoice`](/cua-sdk/reference/spaces/app-core/onboarding-settings#appmodechoice-record), [`AppOnboardingAction`](/cua-sdk/reference/spaces/app-core/onboarding-settings#apponboardingaction-enum), [`AppOnboardingCheckbox`](/cua-sdk/reference/spaces/app-core/onboarding-settings#apponboardingcheckbox-record), [`AppOnboardingCopy`](/cua-sdk/reference/spaces/app-core/onboarding-settings#apponboardingcopy-record), [`AppOnboardingMode`](/cua-sdk/reference/spaces/app-core/onboarding-settings#apponboardingmode-enum), [`AppOnboardingState`](/cua-sdk/reference/spaces/app-core/onboarding-settings#apponboardingstate-record), [`AppOnboardingStep`](/cua-sdk/reference/spaces/app-core/onboarding-settings#apponboardingstep-enum), [`AppOnboardingView`](/cua-sdk/reference/spaces/app-core/onboarding-settings#apponboardingview-record), [`AppPresentationCard`](/cua-sdk/reference/spaces/app-core/onboarding-settings#apppresentationcard-record), [`AppPresentationPreview`](/cua-sdk/reference/spaces/app-core/onboarding-settings#apppresentationpreview-record), [`AppPreviewFrame`](/cua-sdk/reference/spaces/app-core/onboarding-settings#apppreviewframe-record), [`AppPreviewPoint`](/cua-sdk/reference/spaces/app-core/onboarding-settings#apppreviewpoint-record), [`AppPreviewSegment`](/cua-sdk/reference/spaces/app-core/onboarding-settings#apppreviewsegment-record), [`AppPreviewWindow`](/cua-sdk/reference/spaces/app-core/onboarding-settings#apppreviewwindow-record), [`AppSettings`](/cua-sdk/reference/spaces/app-core/onboarding-settings#appsettings-record), [`AppSwitcherTheme`](/cua-sdk/reference/spaces/app-core/onboarding-settings#appswitchertheme-enum), [`AppUsageToggle`](/cua-sdk/reference/spaces/app-core/onboarding-settings#appusagetoggle-record)
@@ -110,8 +112,6 @@ pub fn app_menu_input_from_json(json: String) -> Result<AppMenuInput, CuaError>
**Share sheet**: [`app_share_action_from_json`](/cua-sdk/reference/spaces/app-core/share#app_share_action_from_json), [`app_share_initial`](/cua-sdk/reference/spaces/app-core/share#app_share_initial), [`app_share_input_from_json`](/cua-sdk/reference/spaces/app-core/share#app_share_input_from_json), [`app_share_reduce`](/cua-sdk/reference/spaces/app-core/share#app_share_reduce), [`app_share_state_from_json`](/cua-sdk/reference/spaces/app-core/share#app_share_state_from_json), [`app_share_view`](/cua-sdk/reference/spaces/app-core/share#app_share_view), [`AppRoleOption`](/cua-sdk/reference/spaces/app-core/share#approleoption-record), [`AppShareEntryInput`](/cua-sdk/reference/spaces/app-core/share#appshareentryinput-record), [`AppShareInput`](/cua-sdk/reference/spaces/app-core/share#appshareinput-record), [`AppShareRequest`](/cua-sdk/reference/spaces/app-core/share#appsharerequest-enum), [`AppShareRowView`](/cua-sdk/reference/spaces/app-core/share#appsharerowview-record), [`AppShareSheetAction`](/cua-sdk/reference/spaces/app-core/share#appsharesheetaction-enum), [`AppShareSheetState`](/cua-sdk/reference/spaces/app-core/share#appsharesheetstate-record), [`AppShareSheetView`](/cua-sdk/reference/spaces/app-core/share#appsharesheetview-record)
-**Stream section and facts**: [`app_space_detail_live`](/cua-sdk/reference/spaces/app-core/stream#app_space_detail_live), [`app_stream_desktop_row_id`](/cua-sdk/reference/spaces/app-core/stream#app_stream_desktop_row_id), [`app_stream_pip_click`](/cua-sdk/reference/spaces/app-core/stream#app_stream_pip_click), [`app_stream_pip_reduce`](/cua-sdk/reference/spaces/app-core/stream#app_stream_pip_reduce), [`app_stream_section`](/cua-sdk/reference/spaces/app-core/stream#app_stream_section), [`app_usage_refresh_ms`](/cua-sdk/reference/spaces/app-core/stream#app_usage_refresh_ms), [`AppPipCommand`](/cua-sdk/reference/spaces/app-core/stream#apppipcommand-enum), [`AppPipEvent`](/cua-sdk/reference/spaces/app-core/stream#apppipevent-enum), [`AppSpaceUsage`](/cua-sdk/reference/spaces/app-core/stream#appspaceusage-record), [`AppStreamDisplay`](/cua-sdk/reference/spaces/app-core/stream#appstreamdisplay-record), [`AppStreamRow`](/cua-sdk/reference/spaces/app-core/stream#appstreamrow-record), [`AppStreamRowAction`](/cua-sdk/reference/spaces/app-core/stream#appstreamrowaction-record), [`AppStreamRowActionId`](/cua-sdk/reference/spaces/app-core/stream#appstreamrowactionid-enum), [`AppStreamRowIcon`](/cua-sdk/reference/spaces/app-core/stream#appstreamrowicon-enum), [`AppStreamRowKind`](/cua-sdk/reference/spaces/app-core/stream#appstreamrowkind-enum), [`AppStreamSection`](/cua-sdk/reference/spaces/app-core/stream#appstreamsection-record), [`AppStreamSectionInput`](/cua-sdk/reference/spaces/app-core/stream#appstreamsectioninput-record)
-
**Run on**: [`app_space_host`](/cua-sdk/reference/spaces/app-core/run-on#app_space_host), [`app_wizard_placement_options`](/cua-sdk/reference/spaces/app-core/run-on#app_wizard_placement_options), [`AppPlacementOption`](/cua-sdk/reference/spaces/app-core/run-on#appplacementoption-record), [`AppSpaceHost`](/cua-sdk/reference/spaces/app-core/run-on#appspacehost-record)
**Usage telemetry**: [`app_telemetry_creates`](/cua-sdk/reference/spaces/app-core/telemetry#app_telemetry_creates), [`app_telemetry_enroll`](/cua-sdk/reference/spaces/app-core/telemetry#app_telemetry_enroll), [`app_telemetry_feature`](/cua-sdk/reference/spaces/app-core/telemetry#app_telemetry_feature), [`app_telemetry_launched`](/cua-sdk/reference/spaces/app-core/telemetry#app_telemetry_launched), [`app_telemetry_onboarding`](/cua-sdk/reference/spaces/app-core/telemetry#app_telemetry_onboarding), [`app_telemetry_onboarding_finished`](/cua-sdk/reference/spaces/app-core/telemetry#app_telemetry_onboarding_finished), [`app_telemetry_record`](/cua-sdk/reference/spaces/app-core/telemetry#app_telemetry_record), [`app_telemetry_share`](/cua-sdk/reference/spaces/app-core/telemetry#app_telemetry_share), [`app_telemetry_start`](/cua-sdk/reference/spaces/app-core/telemetry#app_telemetry_start), [`app_telemetry_storage`](/cua-sdk/reference/spaces/app-core/telemetry#app_telemetry_storage), [`app_telemetry_welcome_left`](/cua-sdk/reference/spaces/app-core/telemetry#app_telemetry_welcome_left), [`AppTelemetrySignal`](/cua-sdk/reference/spaces/app-core/telemetry#apptelemetrysignal-enum)
diff --git a/docs/content/docs/cua-sdk/reference/spaces/app-core/onboarding-settings.mdx b/docs/content/docs/cua-sdk/reference/spaces/app-core/onboarding-settings.mdx
index d1a4440f72..ee5a887fa4 100644
--- a/docs/content/docs/cua-sdk/reference/spaces/app-core/onboarding-settings.mdx
+++ b/docs/content/docs/cua-sdk/reference/spaces/app-core/onboarding-settings.mdx
@@ -329,6 +329,7 @@ Returned by [`app_settings_load`](#app_settings_load).
| `launch_at_login` / `launchAtLogin` | `Option<bool>` | | Launch at login, as the user chose it (the first run's Done page or Settings); `None`: never chosen (`crate.login_item.launch_plan`). |
| `experiments` | [`AppExperiments`](/cua-sdk/reference/spaces/app-core/experiments#appexperiments-record) | | Settings, Experiments: every switch off unless turned on (`crate.experiments`). |
| `dismissed_access` / `dismissedAccess` | `Vec<String>` | | Keyvault copies (import ids) the user dismissed from the notch: it no longer shows them, nothing is revoked or wiped (`crate.keyvault.view.prune_dismissed` forgets the gone ones). |
+| `auto_connect` / `autoConnect` | `bool` | | Settings, General: a running Space's desktop streams as soon as it is opened (on by default); off, it waits for Connect (`crate.spaces.cover`). |
## `AppOnboardingAction` enum
diff --git a/docs/content/docs/cua-sdk/reference/spaces/app-core/stream.mdx b/docs/content/docs/cua-sdk/reference/spaces/app-core/stream.mdx
index 009709627d..039e672c76 100644
--- a/docs/content/docs/cua-sdk/reference/spaces/app-core/stream.mdx
+++ b/docs/content/docs/cua-sdk/reference/spaces/app-core/stream.mdx
@@ -17,7 +17,7 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
These APIs are part of the Cua Spaces app export for building Spaces UIs. They are source-available under FSL-1.1-MIT and ship for Swift only (`import CuaSpacesFFI`); the Rust tab shows the `cua-spaces-ffi` crate they come from. The open source SDK packages for Python, TypeScript and Kotlin do not include them.
</Callout>
-`app_stream_section` builds the Stream rows both apps draw: the Desktop with the OS mark and the display's resolution, then one row per window titled by the window, with the app's icon source and a picture-in-picture button. `app_space_detail_live` adds Memory and Storage to the facts from `Space.usage`.
+`app_stream_section` builds the Stream rows both apps draw: the Desktop with the OS mark and the display's resolution, then one row per window titled by the window, with the app's icon source and a picture-in-picture button. `app_space_detail_live` adds Memory and Storage to the facts from `Space.usage`. `app_desktop_cover` says what the preview card shows before the first frame (Connecting, a Connect button, or the Space's own line) and `app_thumbnail_policy` how fresh the shells keep its blurred preview.
## `app_space_detail_live`
@@ -140,6 +140,123 @@ AppPipEvent::Synced { rows: Vec<String> }
| `Closed` | A row's panel closed. Fields: `row: String` |
| `Synced` | The panels open now, as the shell listed them. Fields: `rows: Vec<String>` |
+## `app_desktop_cover`
+
+What a Space's preview card shows before (or instead of) its live
+desktop: "Connecting…", a Connect button, or the Space's own line.
+
+<Tabs items={['Swift', 'Rust']} groupId="sdk-lang" persist>
+<Tab value="Swift">
+
+```swift
+func appDesktopCover(input: AppDesktopCoverInput) -> AppDesktopCover
+```
+
+</Tab>
+<Tab value="Rust">
+
+```rust
+pub fn app_desktop_cover(input: AppDesktopCoverInput) -> AppDesktopCover
+```
+
+</Tab>
+</Tabs>
+
+| Parameter | Type | Default |
+| --- | --- | --- |
+| `input` | [`AppDesktopCoverInput`](#appdesktopcoverinput-record) | required |
+
+**Returns** [`AppDesktopCover`](#appdesktopcover-record)
+
+## `AppDesktopCover` record
+
+Returned by [`app_desktop_cover`](#app_desktop_cover).
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `kind` | [`AppDesktopCoverKind`](#appdesktopcoverkind-enum) | | How it draws. |
+| `text` | `Option<String>` | | The line, centered. |
+| `button` | `Option<String>` | | A button under (or instead of) the line. |
+| `button_help` / `buttonHelp` | `Option<String>` | | Its tooltip. |
+| `open_stream` / `openStream` | `bool` | | The shell opens a stream session now (none is open, and one is wanted). |
+| `retry` | `bool` | | The shell starts the open session again (Try again was pressed). |
+
+## `AppDesktopCoverInput` record
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `can_stream` / `canStream` | `bool` | | The detail's `can_stream`. |
+| `preview_text` / `previewText` | `String` | | The detail's `preview_text` (why it cannot stream). |
+| `auto_connect` / `autoConnect` | `bool` | | Settings: "Connect to the desktop automatically". |
+| `connect_requested` / `connectRequested` | `bool` | | Connect (or Try again) was pressed for this Space. |
+| `stream` | [`AppStreamPhase`](#appstreamphase-enum) | | The shell's stream session. |
+
+## `AppDesktopCoverKind` enum
+
+<Tabs items={['Swift', 'Rust']} groupId="sdk-lang" persist>
+<Tab value="Swift">
+
+```swift
+.stream
+.connecting
+.connect
+.status
+```
+
+</Tab>
+<Tab value="Rust">
+
+```rust
+AppDesktopCoverKind::Stream
+AppDesktopCoverKind::Connecting
+AppDesktopCoverKind::Connect
+AppDesktopCoverKind::Status
+```
+
+</Tab>
+</Tabs>
+
+| Variant | Description |
+| --- | --- |
+| `Stream` | No cover: the live desktop (or the stream view's own badge). |
+| `Connecting` | The preview with "Connecting…". |
+| `Connect` | The preview with a Connect button. |
+| `Status` | The preview with a line (and maybe a button): the Space cannot stream, or the stream failed. |
+
+## `app_thumbnail_policy`
+
+How fresh the shells keep each Space's thumbnail.
+
+<Tabs items={['Swift', 'Rust']} groupId="sdk-lang" persist>
+<Tab value="Swift">
+
+```swift
+func appThumbnailPolicy() -> AppThumbnailPolicy
+```
+
+</Tab>
+<Tab value="Rust">
+
+```rust
+pub fn app_thumbnail_policy() -> AppThumbnailPolicy
+```
+
+</Tab>
+</Tabs>
+
+**Returns** [`AppThumbnailPolicy`](#appthumbnailpolicy-record)
+
+## `AppThumbnailPolicy` record
+
+Returned by [`app_thumbnail_policy`](#app_thumbnail_policy).
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `open_interval_ms` / `openIntervalMs` | `u64` | | While the notch is open: every running Space, this often. |
+| `background_interval_ms` / `backgroundIntervalMs` | `u64` | | Otherwise (the app visible, not in Low Power Mode): a running Space whose thumbnail is older than this gets a new one. |
+| `max_dimension` / `maxDimension` | `u32` | | The long edge of a captured thumbnail, in pixels. |
+| `keep_ms` / `keepMs` | `u64` | | A thumbnail kept on disk longer than this is dropped at launch. |
+
## `AppStreamDisplay` record
| Field | Type | Default | Description |
@@ -189,6 +306,44 @@ Returned by [`app_stream_section`](#app_stream_section).
| `open` | `Vec<String>` | | Rows whose picture in picture is open (row ids). |
| `query` | `String` | | Filter text. |
+## `AppStreamPhase` enum
+
+<Tabs items={['Swift', 'Rust']} groupId="sdk-lang" persist>
+<Tab value="Swift">
+
+```swift
+.noSession
+.idle
+.connecting
+.streaming
+.suspended
+.failed
+```
+
+</Tab>
+<Tab value="Rust">
+
+```rust
+AppStreamPhase::NoSession
+AppStreamPhase::Idle
+AppStreamPhase::Connecting
+AppStreamPhase::Streaming
+AppStreamPhase::Suspended
+AppStreamPhase::Failed
+```
+
+</Tab>
+</Tabs>
+
+| Variant | Description |
+| --- | --- |
+| `NoSession` | No session yet. |
+| `Idle` | A session that has not started. |
+| `Connecting` | Opening (no frame yet). |
+| `Streaming` | Frames arrive. |
+| `Suspended` | Paused by the Space (the stream view says why). |
+| `Failed` | It could not open. |
+
## `AppStreamRowActionId` enum
<Tabs items={['Swift', 'Rust']} groupId="sdk-lang" persist>
diff --git a/docs/content/docs/cua-sdk/reference/spaces/app-core/window.mdx b/docs/content/docs/cua-sdk/reference/spaces/app-core/window.mdx
index e329acc411..646a2a721d 100644
--- a/docs/content/docs/cua-sdk/reference/spaces/app-core/window.mdx
+++ b/docs/content/docs/cua-sdk/reference/spaces/app-core/window.mdx
@@ -620,6 +620,7 @@ Returned by [`app_settings_input_from_json`](#app_settings_input_from_json).
| `login_item` / `loginItem` | [`Option<AppLoginItemInput>`](#apploginiteminput-record) | | Launch at login, once the system was asked (none: no rows). |
| `experiments` | [`AppExperiments`](/cua-sdk/reference/spaces/app-core/experiments#appexperiments-record) | | Settings, Experiments (what the page mentions follows them). |
| `keyvault_auto_wipe` / `keyvaultAutoWipe` | `Option<bool>` | | The Keyvault's auto-wipe, once the broker told it (none: no Keyvault section). |
+| `auto_connect` / `autoConnect` | `Option<bool>` | | "Connect to the desktop automatically" (none: no row; a shell without the preview cover leaves it out). |
## `AppSettingsOption` record
diff --git a/docs/content/docs/cua-sdk/reference/spaces/space.mdx b/docs/content/docs/cua-sdk/reference/spaces/space.mdx
index 5e749c87d6..2672f533a4 100644
--- a/docs/content/docs/cua-sdk/reference/spaces/space.mdx
+++ b/docs/content/docs/cua-sdk/reference/spaces/space.mdx
@@ -31,7 +31,7 @@ Returned by [`Spaces.space`](/cua-sdk/reference/spaces#spacesspace).
| [`hotspot_status`](#spacehotspot_status) | This Space's hotspot status. |
| [`list_tools`](#spacelist_tools) | Tools of the Space's MCP service (`driver`, the default). |
| [`request_site_login`](#spacerequest_site_login) | Signs in to a site in this Space's browser with a password the user saved in the Cua Keyvault. |
-| [`screenshot`](#spacescreenshot) | Captures the Space's display (the app's tile thumbnails): PNG at full size on the primary display unless `options` say otherwise. |
+| [`screenshot`](#spacescreenshot) | Captures the Space's display: PNG at full size on the primary display unless `options` say otherwise (for a small preview, `Space.thumbnail` reads the shared cache instead). |
| [`send_file`](#spacesend_file) | Drops a host file or folder into the Space's `~/Downloads[/subdir]` (TeleportService.ReceiveFiles, per-file SHA-256). |
| [`set_presence_settings`](#spaceset_presence_settings) | Sets this Space's presence settings. |
| [`share`](#spaceshare) | Lets `who` (a verified email or an account id) watch (`viewer`, the default) or use (`editor`) this Space through the relay. |
@@ -59,6 +59,7 @@ Returned by [`Spaces.space`](/cua-sdk/reference/spaces#spacesspace).
| [`stream_session`](/cua-sdk/reference/spaces/streams#spacestream_session) | Opens a media session and delivers keyframe-gated encoded frames and audio to the sinks (one delivery thread; decoding stays with the caller). |
| [`teleport`](/cua-sdk/reference/spaces/teleport#spaceteleport) | Teleports `app`'s session into this Space. |
| [`teleport_manifest`](/cua-sdk/reference/spaces/teleport#spaceteleport_manifest) | What teleporting `app` (`full` or `tabs`) would move from this host. |
+| [`thumbnail`](/cua-sdk/reference/spaces/windows#spacethumbnail) | The Space's latest thumbnail (a small JPEG of its primary display) from the cache every client on this machine shares: returned at once when it is younger than `max_age_ms` (unset: any age), else captured fresh through cua-spacesd and kept for the next caller. |
| [`usage`](/cua-sdk/reference/spaces/windows#spaceusage) | Memory and storage use now (cheap: poll it at a low rate while a detail is visible). |
| [`websocket_headers`](/cua-sdk/reference/spaces/streams#spacewebsocket_headers) | Headers a media WebSocket to this Space needs besides its ticket. |
| [`window_thumbnail`](/cua-sdk/reference/spaces/windows#spacewindow_thumbnail) | A small JPEG preview of one of the Space's windows (`window_id` and `epoch` from `windows`), at most `max_dimension` px, reused for a few seconds (the SDK's preview cache); `None` when the guest captured nothing. |
@@ -466,10 +467,10 @@ pub async fn request_site_login(&self, url: String, options: Option<SiteLoginOpt
### `Space.screenshot`
-Captures the Space's display (the app's tile thumbnails): PNG at
-full size on the primary display unless `options` say otherwise.
-Fails with `CapabilityMissing` (`spacesd`) when the image runs no
-cua-spacesd.
+Captures the Space's display: PNG at full size on the primary
+display unless `options` say otherwise (for a small preview,
+`Space.thumbnail` reads the shared cache instead). Fails with
+`CapabilityMissing` (`spacesd`) when the image runs no cua-spacesd.
<Tabs items={['Python', 'TypeScript', 'Swift', 'Kotlin', 'Rust']} groupId="sdk-lang" persist>
<Tab value="Python">
diff --git a/docs/content/docs/cua-sdk/reference/spaces/windows.mdx b/docs/content/docs/cua-sdk/reference/spaces/windows.mdx
index 5bdf3f620c..81b3b8a1d5 100644
--- a/docs/content/docs/cua-sdk/reference/spaces/windows.mdx
+++ b/docs/content/docs/cua-sdk/reference/spaces/windows.mdx
@@ -12,7 +12,7 @@ description: "A Space's app icons (batched, through the SDK's one icon cache), w
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
-`app_icons` answers a whole window list in one call: cached icons come from memory or `$CUA_HOME/cache/icons`, and every miss costs one guest round trip. `window_thumbnail` previews one window, reused for a few seconds. `displays` lists the displays with their resolution and `usage` the memory and storage use.
+`app_icons` answers a whole window list in one call: cached icons come from memory or `$CUA_HOME/cache/icons`, and every miss costs one guest round trip. `thumbnail` is the Space's latest small preview from the cache every client on the machine shares (`$CUA_HOME/cache/thumbnails`, kept fresh by the daemon while someone asks). `window_thumbnail` previews one window, reused for a few seconds. `displays` lists the displays with their resolution and `usage` the memory and storage use.
## Windows, icons and displays
@@ -127,6 +127,61 @@ pub async fn app_icon(&self, app_name: String, app_id: String, pid: u32) -> Resu
**Returns** [`Option<SpaceAppIcon>`](#spaceappicon-record) · **Async** · **Raises** [`CuaError`](/cua-sdk/reference/errors)
+### `Space.thumbnail`
+
+The Space's latest thumbnail (a small JPEG of its primary display)
+from the cache every client on this machine shares: returned at
+once when it is younger than `max_age_ms` (unset: any age), else
+captured fresh through cua-spacesd and kept for the next caller.
+When that capture fails, the older one comes back (`captured_at_ms`
+says how old). Asking keeps the daemon refreshing running Spaces'
+thumbnails in the background for a while (about every 90 s).
+
+<Tabs items={['Python', 'TypeScript', 'Swift', 'Kotlin', 'Rust']} groupId="sdk-lang" persist>
+<Tab value="Python">
+
+```python
+async def thumbnail(self, max_age_ms: Optional[int]) -> SpaceThumbnail
+```
+
+</Tab>
+<Tab value="TypeScript">
+
+```ts
+thumbnail(maxAgeMs: bigint | undefined, asyncOpts_?: { signal: AbortSignal }): Promise<SpaceThumbnail>
+```
+
+</Tab>
+<Tab value="Swift">
+
+```swift
+func thumbnail(maxAgeMs: UInt64?) async throws -> SpaceThumbnail
+```
+
+</Tab>
+<Tab value="Kotlin">
+
+```kotlin
+@Throws(CuaException::class)
+suspend fun thumbnail(maxAgeMs: ULong?): SpaceThumbnail
+```
+
+</Tab>
+<Tab value="Rust">
+
+```rust
+pub async fn thumbnail(&self, max_age_ms: Option<u64>) -> Result<SpaceThumbnail, CuaError>
+```
+
+</Tab>
+</Tabs>
+
+| Parameter | Type | Default |
+| --- | --- | --- |
+| `max_age_ms` | `Option<u64>` | required |
+
+**Returns** [`SpaceThumbnail`](#spacethumbnail-record) · **Async** · **Raises** [`CuaError`](/cua-sdk/reference/errors)
+
### `Space.window_thumbnail`
A small JPEG preview of one of the Space's windows (`window_id` and
@@ -311,6 +366,21 @@ Returned by [`Space.displays`](#spacedisplays).
| `height_px` / `heightPx` | `u32` | | Framebuffer height in physical pixels. |
| `scale_factor` / `scaleFactor` | `f64` | | Physical pixels per logical point. |
+## `SpaceThumbnail` record
+
+A Space's latest thumbnail, from the cache every client on this machine
+shares (`crate.native.spaces.Space.thumbnail`).
+
+Returned by [`Space.thumbnail`](#spacethumbnail).
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `image` | `Vec<u8>` | | Encoded image (a small JPEG of the primary display). |
+| `format` | [`ImageFormat`](/cua-sdk/reference/spacesd/computer#imageformat-enum) | | Encoding. |
+| `width` | `u32` | | Pixel width. |
+| `height` | `u32` | | Pixel height. |
+| `captured_at_ms` / `capturedAtMs` | `u64` | | When it was captured, Unix milliseconds. |
+
## `SpaceUsage` record
Memory and storage use (`Space.usage`). A size is the guest's own
diff --git a/docs/content/docs/cua-sdk/reference/types.mdx b/docs/content/docs/cua-sdk/reference/types.mdx
index 01513452e5..b7dbc7e77d 100644
--- a/docs/content/docs/cua-sdk/reference/types.mdx
+++ b/docs/content/docs/cua-sdk/reference/types.mdx
@@ -48,9 +48,9 @@ Renamed members: in Kotlin, objects implement `AutoCloseable`, whose `close()` f
## All items
-290 items. Methods are listed on their object.
+291 items. Methods are listed on their object.
-The 678 items of the Cua Spaces app export (source-available, FSL-1.1-MIT, Swift only) are listed on their pages: [Decoded media](/cua-sdk/reference/spaces/decoded-media), [Host teleport](/cua-sdk/reference/spaces/teleport-host), [Teleport an app](/cua-sdk/reference/spaces/teleport-apps), [Spaces app core](/cua-sdk/reference/spaces/app-core#all-items), [App core: Cua Volume storage, mount and sync](/cua-sdk/reference/spaces/volume-app-core#all-items), [App core: agents, drive, notifications](/cua-sdk/reference/spaces/agents-app-core#all-items).
+The 685 items of the Cua Spaces app export (source-available, FSL-1.1-MIT, Swift only) are listed on their pages: [Decoded media](/cua-sdk/reference/spaces/decoded-media), [Host teleport](/cua-sdk/reference/spaces/teleport-host), [Teleport an app](/cua-sdk/reference/spaces/teleport-apps), [Spaces app core](/cua-sdk/reference/spaces/app-core#all-items), [App core: Cua Volume storage, mount and sync](/cua-sdk/reference/spaces/volume-app-core#all-items), [App core: agents, drive, notifications](/cua-sdk/reference/spaces/agents-app-core#all-items).
| Item | Kind | Summary |
| --- | --- | --- |
@@ -311,6 +311,7 @@ The 678 items of the Cua Spaces app export (source-available, FSL-1.1-MIT, Swift
| [`SpaceStreamSession`](/cua-sdk/reference/spaces/streams#spacestreamsession) | object | A live Space media session (see `Space.stream_session`). |
| [`SpaceStreamStats`](/cua-sdk/reference/spaces/streams#spacestreamstats-record) | record | Delivery counters of a `SpaceStreamSession`. |
| [`SpaceStreamTicket`](/cua-sdk/reference/spaces/streams#spacestreamticket-record) | record | A minted media session. |
+| [`SpaceThumbnail`](/cua-sdk/reference/spaces/windows#spacethumbnail-record) | record | A Space's latest thumbnail, from the cache every client on this machine shares (`crate.native.spaces.Space.thumbnail`). |
| [`SpaceToolInfo`](/cua-sdk/reference/spaces/space#spacetoolinfo-record) | record | A tool of a Space's MCP service. |
| [`SpaceToolResult`](/cua-sdk/reference/spaces/space#spacetoolresult-record) | record | The result of a tool call (MCP content as JSON). |
| [`SpaceTransferReport`](/cua-sdk/reference/spaces/space#spacetransferreport-record) | record | Result of `Space.upload` / `Space.download`. |
diff --git a/libs/cua/crates/cua-daemon/src/server.rs b/libs/cua/crates/cua-daemon/src/server.rs
index 750a688fe4..d91f66f3f8 100644
--- a/libs/cua/crates/cua-daemon/src/server.rs
+++ b/libs/cua/crates/cua-daemon/src/server.rs
@@ -282,6 +282,10 @@ pub async fn start(runtime: Runtime, config: ServerConfig) -> Result<DaemonHandl
};
#[cfg(feature = "spaces")]
let host_spaces = cua_spaces::host_spaces::HostSpacesServer::new(runtime.spaces().clone());
+ // Running Spaces' thumbnails stay fresh while a client asks for them
+ // (the Spaces apps' notch and previews, SDK scripts); idle otherwise.
+ #[cfg(feature = "spaces")]
+ let _thumbnails = runtime.spaces().spawn_thumbnail_refresh();
let own = std::env::current_exe()
.ok()
.and_then(|e| crate::identity::of(&e));
diff --git a/libs/cua/crates/cua-daemon/src/spaces_svc.rs b/libs/cua/crates/cua-daemon/src/spaces_svc.rs
index 278448b175..2965314941 100644
--- a/libs/cua/crates/cua-daemon/src/spaces_svc.rs
+++ b/libs/cua/crates/cua-daemon/src/spaces_svc.rs
@@ -536,6 +536,25 @@ mod imp {
.collect();
ok(pb::ListHostsResponse { hosts })
}
+
+ async fn get_space_thumbnail(
+ &self,
+ req: tonic::Request<pb::GetSpaceThumbnailRequest>,
+ ) -> R<pb::GetSpaceThumbnailResponse> {
+ let r = req.into_inner();
+ let t = self
+ .spaces()
+ .thumbnail(&r.space, r.max_age.as_ref().map(from_dur))
+ .await
+ .map_err(|e| st(e.into()))?;
+ ok(pb::GetSpaceThumbnailResponse {
+ image: t.image,
+ format: t.format,
+ width: t.width,
+ height: t.height,
+ captured_at: Some(crate::convert::ts(t.captured_at)),
+ })
+ }
}
}
@@ -646,5 +665,11 @@ mod imp {
) -> R<pb::ListHostsResponse> {
off()
}
+ async fn get_space_thumbnail(
+ &self,
+ _: tonic::Request<pb::GetSpaceThumbnailRequest>,
+ ) -> R<pb::GetSpaceThumbnailResponse> {
+ off()
+ }
}
}
diff --git a/libs/cua/crates/cua-daemon/tests/thumbnails.rs b/libs/cua/crates/cua-daemon/tests/thumbnails.rs
new file mode 100644
index 0000000000..c21124d167
--- /dev/null
+++ b/libs/cua/crates/cua-daemon/tests/thumbnails.rs
@@ -0,0 +1,108 @@
+//! `SpaceService.GetSpaceThumbnail` over the daemon's loopback listener:
+//! the daemon's cache answers within `max_age`, falls back to the older
+//! image when a fresh capture fails, keeps it across a daemon restart, and
+//! says not found when it has nothing. Temp dirs only; no Space answers.
+
+use cua_daemon::client::{DaemonAddress, DaemonClient};
+use cua_daemon::server::{DaemonHandle, ServerConfig, start};
+use cua_daemon::{Runtime as DaemonRuntime, RuntimeConfig};
+use cua_proto::daemon::v1 as pb;
+use cua_spaces::thumbnails::Thumbnail;
+use std::time::{Duration, UNIX_EPOCH};
+
+const ID: &str = "direct:127.0.0.1:9";
+
+async fn daemon(dir: &std::path::Path) -> (DaemonRuntime, DaemonHandle, DaemonClient) {
+ let runtime = DaemonRuntime::new(RuntimeConfig {
+ state_dir: Some(dir.join("sandboxes")),
+ spaces_home: Some(dir.to_path_buf()),
+ ..Default::default()
+ })
+ .unwrap();
+ let handle = start(
+ runtime.clone(),
+ ServerConfig {
+ socket_path: None,
+ loopback: Some(([127, 0, 0, 1], 0).into()),
+ token: "t0k3n".into(),
+ discovery_path: None,
+ bridge_ticket_ttl: Duration::from_secs(60),
+ },
+ )
+ .await
+ .unwrap();
+ let client = DaemonClient::new(DaemonAddress::Url {
+ url: handle.loopback_url.clone().unwrap(),
+ token: handle.token.clone(),
+ })
+ .unwrap();
+ (runtime, handle, client)
+}
+
+fn ask(max_age: Option<Duration>) -> pb::GetSpaceThumbnailRequest {
+ pb::GetSpaceThumbnailRequest {
+ space: ID.into(),
+ max_age: max_age.map(|d| pbjson_types::Duration {
+ seconds: d.as_secs() as i64,
+ nanos: d.subsec_nanos() as i32,
+ }),
+ }
+}
+
+#[tokio::test]
+async fn the_daemon_serves_its_shared_thumbnail_cache() {
+ let dir = tempfile::tempdir().unwrap();
+ let (runtime, handle, client) = daemon(dir.path()).await;
+ // Nothing cached, nothing answers: an error, not an empty image.
+ assert!(
+ client
+ .spaces()
+ .get_space_thumbnail(ask(None))
+ .await
+ .is_err()
+ );
+
+ let captured_at = UNIX_EPOCH + Duration::from_millis(1_800_000_000_000);
+ runtime.spaces().thumbnails().put(
+ ID,
+ Thumbnail {
+ image: vec![0xff, 0xd8, 0xff, 0xd9],
+ format: "jpeg".into(),
+ width: 320,
+ height: 200,
+ captured_at,
+ },
+ );
+ let r = client
+ .spaces()
+ .get_space_thumbnail(ask(None))
+ .await
+ .unwrap()
+ .into_inner();
+ assert_eq!(
+ (r.image.len(), r.format.as_str(), r.width, r.height),
+ (4, "jpeg", 320, 200)
+ );
+ assert_eq!(r.captured_at.unwrap().seconds, 1_800_000_000);
+ // Older than max_age: the capture fails, the older image comes back.
+ let stale = client
+ .spaces()
+ .get_space_thumbnail(ask(Some(Duration::ZERO)))
+ .await
+ .unwrap()
+ .into_inner();
+ assert_eq!(stale.captured_at, r.captured_at);
+ handle.shutdown();
+ drop((runtime, handle, client));
+
+ // A new daemon on the same home: the cache is still there.
+ let (_runtime, handle, client) = daemon(dir.path()).await;
+ let again = client
+ .spaces()
+ .get_space_thumbnail(ask(None))
+ .await
+ .unwrap()
+ .into_inner();
+ assert_eq!(again.image, vec![0xff, 0xd8, 0xff, 0xd9]);
+ handle.shutdown();
+}
diff --git a/libs/cua/crates/cua-sdk/src/native/spaces.rs b/libs/cua/crates/cua-sdk/src/native/spaces.rs
index ac3a614f81..966a41192a 100644
--- a/libs/cua/crates/cua-sdk/src/native/spaces.rs
+++ b/libs/cua/crates/cua-sdk/src/native/spaces.rs
@@ -3027,10 +3027,10 @@ impl Space {
.await
}
- /// Captures the Space's display (the app's tile thumbnails): PNG at
- /// full size on the primary display unless `options` say otherwise.
- /// Fails with `CapabilityMissing` (`spacesd`) when the image runs no
- /// cua-spacesd.
+ /// Captures the Space's display: PNG at full size on the primary
+ /// display unless `options` say otherwise (for a small preview,
+ /// [`Space::thumbnail`] reads the shared cache instead). Fails with
+ /// `CapabilityMissing` (`spacesd`) when the image runs no cua-spacesd.
pub async fn screenshot(
&self,
options: Option<crate::types::ScreenshotOptions>,
@@ -3044,6 +3044,65 @@ impl Space {
.await
}
+ /// The Space's latest thumbnail (a small JPEG of its primary display)
+ /// from the cache every client on this machine shares: returned at
+ /// once when it is younger than `max_age_ms` (unset: any age), else
+ /// captured fresh through cua-spacesd and kept for the next caller.
+ /// When that capture fails, the older one comes back (`captured_at_ms`
+ /// says how old). Asking keeps the daemon refreshing running Spaces'
+ /// thumbnails in the background for a while (about every 90 s).
+ pub async fn thumbnail(&self, max_age_ms: Option<u64>) -> Result<crate::types::SpaceThumbnail> {
+ let host = self.host.clone();
+ let id = self.info.id.clone();
+ run(async move {
+ let max_age = max_age_ms.map(Duration::from_millis);
+ Ok(match &host {
+ Host::Embedded(s) => {
+ let t = s.thumbnail(&id, max_age).await?;
+ crate::types::SpaceThumbnail {
+ format: thumbnail_format(&t.format),
+ width: t.width,
+ height: t.height,
+ captured_at_ms: t
+ .captured_at
+ .duration_since(std::time::UNIX_EPOCH)
+ .map(|d| d.as_millis() as u64)
+ .unwrap_or(0),
+ image: t.image,
+ }
+ }
+ Host::Daemon(d) => {
+ let r = d
+ .spaces()
+ .get_space_thumbnail(dpb::GetSpaceThumbnailRequest {
+ space: id,
+ max_age: max_age.map(|d| pbjson_types::Duration {
+ seconds: d.as_secs() as i64,
+ nanos: d.subsec_nanos() as i32,
+ }),
+ })
+ .await
+ .map_err(daemon_err)?
+ .into_inner();
+ let captured_at_ms = r
+ .captured_at
+ .map(|t| {
+ (t.seconds.max(0) as u64) * 1000 + (t.nanos.max(0) as u64) / 1_000_000
+ })
+ .unwrap_or(0);
+ crate::types::SpaceThumbnail {
+ image: r.image,
+ format: thumbnail_format(&r.format),
+ width: r.width,
+ height: r.height,
+ captured_at_ms,
+ }
+ }
+ })
+ })
+ .await
+ }
+
/// Calls a tool of the Space's MCP service with JSON arguments.
pub async fn call_tool(
&self,
@@ -5119,3 +5178,12 @@ impl Spaces {
self.volume_audit(limit).await
}
}
+
+/// The thumbnail cache's format word (`jpeg`, `png`, `webp`).
+fn thumbnail_format(word: &str) -> crate::types::ImageFormat {
+ match word {
+ "png" => crate::types::ImageFormat::Png,
+ "webp" => crate::types::ImageFormat::Webp,
+ _ => crate::types::ImageFormat::Jpeg,
+ }
+}
diff --git a/libs/cua/crates/cua-sdk/src/types.rs b/libs/cua/crates/cua-sdk/src/types.rs
index b1b1b777aa..a186cea2c9 100644
--- a/libs/cua/crates/cua-sdk/src/types.rs
+++ b/libs/cua/crates/cua-sdk/src/types.rs
@@ -242,6 +242,22 @@ pub struct Screenshot {
pub screenshot_id: String,
}
+/// A Space's latest thumbnail, from the cache every client on this machine
+/// shares ([`crate::native::spaces::Space::thumbnail`]).
+#[derive(Debug, Clone, PartialEq, uniffi::Record)]
+pub struct SpaceThumbnail {
+ /// Encoded image (a small JPEG of the primary display).
+ pub image: Vec<u8>,
+ /// Encoding.
+ pub format: ImageFormat,
+ /// Pixel width.
+ pub width: u32,
+ /// Pixel height.
+ pub height: u32,
+ /// When it was captured, Unix milliseconds.
+ pub captured_at_ms: u64,
+}
+
/// A point.
#[derive(Debug, Clone, Copy, PartialEq, uniffi::Record)]
pub struct Point {
diff --git a/libs/cua/crates/cua-sdk/tests/thumbnails.rs b/libs/cua/crates/cua-sdk/tests/thumbnails.rs
new file mode 100644
index 0000000000..4b2d808e4f
--- /dev/null
+++ b/libs/cua/crates/cua-sdk/tests/thumbnails.rs
@@ -0,0 +1,61 @@
+//! `Space.thumbnail` (the SDK face of the shared thumbnail cache) against
+//! the in-process mock spacesd: the first call captures, a call within
+//! `max_age_ms` is answered from the cache without touching the guest, a
+//! zero `max_age_ms` captures again, and a new runtime on the same cua home
+//! still has it. No host effects.
+
+use cua_sdk::{Cua, CuaConfig};
+use cua_spacesd_client::testing::MockServer;
+
+fn cua(dir: &tempfile::TempDir) -> std::sync::Arc<Cua> {
+ Cua::embedded(CuaConfig {
+ state_dir: Some(dir.path().join("sandboxes").display().to_string()),
+ spaces_home: Some(dir.path().join("cua").display().to_string()),
+ fleet_pool_home: Some(dir.path().join("pools").display().to_string()),
+ fleet_from_env: false,
+ fleet_from_session: false,
+ ..Default::default()
+ })
+ .unwrap()
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn thumbnails_come_from_the_cache_within_max_age() {
+ let dir = tempfile::tempdir().unwrap();
+ let server = MockServer::start(Default::default()).await;
+ let shots = || server.state.observed.screenshots.lock().unwrap().len();
+ let c = cua(&dir);
+ let info = c
+ .spaces()
+ .add(server.url(), None, Some("lab".into()))
+ .await
+ .unwrap();
+ let space = c.spaces().space(info.id.clone()).await.unwrap();
+
+ let first = space.thumbnail(None).await.unwrap();
+ assert!(!first.image.is_empty() && first.captured_at_ms > 0);
+ assert_eq!(shots(), 1, "nothing cached: captured");
+ // A small JPEG of the primary display was asked for.
+ {
+ let asked = server.state.observed.screenshots.lock().unwrap();
+ assert_eq!(
+ asked[0].format,
+ cua_spacesd_client::pb::ImageFormat::Jpeg as i32
+ );
+ assert!(asked[0].max_dimension > 0 && asked[0].max_dimension <= 480);
+ }
+
+ let cached = space.thumbnail(Some(60_000)).await.unwrap();
+ assert_eq!(cached, first);
+ assert_eq!(shots(), 1, "within max_age: no capture");
+
+ let fresh = space.thumbnail(Some(0)).await.unwrap();
+ assert_eq!(shots(), 2, "max_age 0: captured again");
+ assert!(fresh.captured_at_ms >= first.captured_at_ms);
+
+ // Another runtime on the same home (another client): the cache.
+ let other = cua(&dir).spaces().space(info.id).await.unwrap();
+ let shared = other.thumbnail(None).await.unwrap();
+ assert_eq!(shared.image, fresh.image);
+ assert_eq!(shots(), 2);
+}
diff --git a/libs/cua/crates/cua-spaces-app-core/src/installer.rs b/libs/cua/crates/cua-spaces-app-core/src/installer.rs
index a6fe0304b0..8468a9e0bb 100644
--- a/libs/cua/crates/cua-spaces-app-core/src/installer.rs
+++ b/libs/cua/crates/cua-spaces-app-core/src/installer.rs
@@ -364,18 +364,29 @@ fn on_path_before(path_env: &str, bin_dir: &Path) -> bool {
true
}
+/// `ETXTBSY` ("text file busy") on Linux and macOS.
+const ETXTBSY: i32 = 26;
+
/// `cua --version`, first line, or `None` if it does not run.
pub async fn cli_version(cli: &Path) -> Option<String> {
- let run = tokio::process::Command::new(cli)
- .arg("--version")
- .stdin(Stdio::null())
- .stderr(Stdio::null())
- .kill_on_drop(true)
- .output();
- let out = tokio::time::timeout(VERSION_TIMEOUT, run)
- .await
- .ok()?
- .ok()?;
+ // A file just written can be briefly "busy" to exec (ETXTBSY) while a
+ // process forked elsewhere still holds its write handle: try again.
+ let mut attempt = 0;
+ let out = loop {
+ let run = tokio::process::Command::new(cli)
+ .arg("--version")
+ .stdin(Stdio::null())
+ .stderr(Stdio::null())
+ .kill_on_drop(true)
+ .output();
+ match tokio::time::timeout(VERSION_TIMEOUT, run).await.ok()? {
+ Err(e) if e.raw_os_error() == Some(ETXTBSY) && attempt < 10 => {
+ attempt += 1;
+ tokio::time::sleep(std::time::Duration::from_millis(20)).await;
+ }
+ r => break r.ok()?,
+ }
+ };
if !out.status.success() {
return None;
}
diff --git a/libs/cua/crates/cua-spaces-app-core/src/settings.rs b/libs/cua/crates/cua-spaces-app-core/src/settings.rs
index e98ec6b808..e1e1421961 100644
--- a/libs/cua/crates/cua-spaces-app-core/src/settings.rs
+++ b/libs/cua/crates/cua-spaces-app-core/src/settings.rs
@@ -61,6 +61,10 @@ pub struct AppSettings {
/// longer shows them, nothing is revoked or wiped
/// ([`crate::keyvault::view::prune_dismissed`] forgets the gone ones).
pub dismissed_access: Vec<String>,
+ /// Settings, General: a running Space's desktop streams as soon as it
+ /// is opened (on by default); off, it waits for Connect
+ /// ([`crate::spaces::cover`]).
+ pub auto_connect: bool,
}
impl Default for AppSettings {
@@ -77,6 +81,7 @@ impl Default for AppSettings {
launch_at_login: None,
experiments: Experiments::default(),
dismissed_access: vec![],
+ auto_connect: true,
}
}
}
@@ -243,6 +248,9 @@ pub struct SettingsInput {
/// The Keyvault's auto-wipe, once the broker told it (none: no
/// Keyvault section).
pub keyvault_auto_wipe: Option<bool>,
+ /// "Connect to the desktop automatically" (none: no row; a shell
+ /// without the preview cover leaves it out).
+ pub auto_connect: Option<bool>,
}
impl Default for SettingsInput {
@@ -263,10 +271,26 @@ impl Default for SettingsInput {
login_item: None,
experiments: Experiments::default(),
keyvault_auto_wipe: None,
+ auto_connect: None,
}
}
}
+/// The auto-connect switch's label.
+pub const AUTO_CONNECT_LABEL: &str = "Connect to the desktop automatically";
+
+/// The auto-connect switch: row id `auto-connect`, options `on` and `off`.
+pub fn auto_connect_row(on: bool) -> SettingsRow {
+ let mut r = row("auto-connect", SettingsRowKind::Toggle, AUTO_CONNECT_LABEL);
+ r.options = vec![opt("on", "On", on), opt("off", "Off", !on)];
+ r.help = Some(if on {
+ "Opening a running Space shows its live desktop".into()
+ } else {
+ "Opening a running Space shows a preview and a Connect button".into()
+ });
+ r
+}
+
/// The Keyvault auto-wipe switch's label.
pub const AUTO_WIPE_LABEL: &str = "Wipe access from Spaces automatically";
@@ -499,6 +523,9 @@ pub fn page(input: &SettingsInput) -> SettingsPage {
.map(|l| crate::login_item::rows_with(l, input.experiments.cua_volume))
.unwrap_or_default();
general.push(notch);
+ if let Some(on) = input.auto_connect {
+ general.push(auto_connect_row(on));
+ }
// Where New Space starts: only a choice while the apps offer Cua Cloud.
if crate::model::CLOUD_SPACES_OFFERED {
let mut location = row("default-location", Choice, "New Spaces run on");
@@ -779,6 +806,45 @@ mod tests {
assert_eq!(rows[2].id, "notch");
}
+ #[test]
+ fn auto_connect_is_on_by_default_and_follows_the_notch_row() {
+ assert!(AppSettings::default().auto_connect);
+ // A settings file from before the switch: on.
+ let old: AppSettings = serde_json::from_str(r#"{"menuBar":true}"#).unwrap();
+ assert!(old.auto_connect);
+ let off: AppSettings = serde_json::from_str(r#"{"autoConnect":false}"#).unwrap();
+ assert!(!off.auto_connect);
+ let general = |input: &SettingsInput| {
+ page(input)
+ .sections
+ .into_iter()
+ .find(|s| s.id == "general")
+ .unwrap()
+ .rows
+ };
+ // Not passed (a shell without the cover): no row.
+ assert!(
+ !general(&SettingsInput::default())
+ .iter()
+ .any(|r| r.id == "auto-connect")
+ );
+ let rows = general(&SettingsInput {
+ auto_connect: Some(true),
+ ..Default::default()
+ });
+ let i = rows.iter().position(|r| r.id == "auto-connect").unwrap();
+ assert_eq!(rows[i - 1].id, "notch");
+ let r = &rows[i];
+ assert_eq!(
+ (r.kind, r.label.as_str()),
+ (SettingsRowKind::Toggle, AUTO_CONNECT_LABEL)
+ );
+ let on = |r: &SettingsRow| r.options.iter().find(|o| o.id == "on").unwrap().active;
+ assert!(on(r));
+ assert!(!on(&auto_connect_row(false)));
+ assert!(!AUTO_CONNECT_LABEL.contains('\u{2014}'));
+ }
+
/// Cua Volume off: no Storage section, and the launch-at-login line
/// does not promise a Volume; on: Storage after General.
#[test]
diff --git a/libs/cua/crates/cua-spaces-app-core/src/spaces/cover.rs b/libs/cua/crates/cua-spaces-app-core/src/spaces/cover.rs
new file mode 100644
index 0000000000..4b5981ab85
--- /dev/null
+++ b/libs/cua/crates/cua-spaces-app-core/src/spaces/cover.rs
@@ -0,0 +1,315 @@
+// SPDX-License-Identifier: FSL-1.1-MIT
+// Copyright (c) 2026 Cua AI, Inc.
+
+//! What a Space's preview card shows before (or instead of) its live
+//! desktop: the cover.
+//!
+//! - A running Space opens its desktop stream at once ("Connect to the
+//! desktop automatically", on by default) and shows "Connecting…" over a
+//! blurred preview until the first frame.
+//! - With that setting off, it shows the same preview with a Connect
+//! button; pressing it starts the stream (then "Connecting…", then the
+//! live desktop).
+//! - A Space that cannot stream (off, starting, being created or deleted,
+//! unreachable) shows the detail's own line ([`super::sidebar::SpaceDetail::preview_text`]).
+//! - A stream that failed says so, with Try again.
+//!
+//! The preview is the Space's latest thumbnail, the same one the notch
+//! tiles show ([`thumbnail_policy`] says how fresh the shells keep it).
+//! Shells draw it with a strong blur and a slight dim, or plain black when
+//! there is none yet.
+
+use serde::{Deserialize, Serialize};
+
+/// The cover's line while the stream opens.
+pub const CONNECTING_TEXT: &str = "Connecting\u{2026}";
+/// The manual-connect button.
+pub const CONNECT_BUTTON: &str = "Connect";
+/// Its tooltip.
+pub const CONNECT_HELP: &str = "Show the live desktop";
+/// The line when the stream could not open.
+pub const FAILED_TEXT: &str = "Could not connect to the desktop";
+/// The retry button.
+pub const RETRY_BUTTON: &str = "Try again";
+
+/// Where the shell's stream session stands.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum StreamPhase {
+ /// No session yet.
+ NoSession,
+ /// A session that has not started.
+ Idle,
+ /// Opening (no frame yet).
+ Connecting,
+ /// Frames arrive.
+ Streaming,
+ /// Paused by the Space (the stream view says why).
+ Suspended,
+ /// It could not open.
+ Failed,
+}
+
+/// What the cover is built from.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DesktopCoverInput {
+ /// The detail's `can_stream`.
+ pub can_stream: bool,
+ /// The detail's `preview_text` (why it cannot stream).
+ pub preview_text: String,
+ /// Settings: "Connect to the desktop automatically".
+ pub auto_connect: bool,
+ /// Connect (or Try again) was pressed for this Space.
+ pub connect_requested: bool,
+ /// The shell's stream session.
+ pub stream: StreamPhase,
+}
+
+/// How the cover draws.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum DesktopCoverKind {
+ /// No cover: the live desktop (or the stream view's own badge).
+ Stream,
+ /// The preview with "Connecting…".
+ Connecting,
+ /// The preview with a Connect button.
+ Connect,
+ /// The preview with a line (and maybe a button): the Space cannot
+ /// stream, or the stream failed.
+ Status,
+}
+
+/// The cover.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DesktopCover {
+ /// How it draws.
+ pub kind: DesktopCoverKind,
+ /// The line, centered.
+ pub text: Option<String>,
+ /// A button under (or instead of) the line.
+ pub button: Option<String>,
+ /// Its tooltip.
+ pub button_help: Option<String>,
+ /// The shell opens a stream session now (none is open, and one is
+ /// wanted).
+ pub open_stream: bool,
+ /// The shell starts the open session again (Try again was pressed).
+ pub retry: bool,
+}
+
+/// The cover for `input`.
+pub fn desktop_cover(input: &DesktopCoverInput) -> DesktopCover {
+ let cover = |kind, text: Option<&str>, button: Option<&str>, help: Option<&str>| DesktopCover {
+ kind,
+ text: text.map(str::to_string),
+ button: button.map(str::to_string),
+ button_help: help.map(str::to_string),
+ open_stream: false,
+ retry: false,
+ };
+ if !input.can_stream {
+ return cover(
+ DesktopCoverKind::Status,
+ Some(&input.preview_text),
+ None,
+ None,
+ );
+ }
+ let wanted = input.auto_connect || input.connect_requested;
+ match input.stream {
+ StreamPhase::Streaming | StreamPhase::Suspended => {
+ cover(DesktopCoverKind::Stream, None, None, None)
+ }
+ StreamPhase::Failed => DesktopCover {
+ retry: input.connect_requested,
+ ..cover(
+ DesktopCoverKind::Status,
+ Some(FAILED_TEXT),
+ Some(RETRY_BUTTON),
+ None,
+ )
+ },
+ StreamPhase::NoSession | StreamPhase::Idle if !wanted => cover(
+ DesktopCoverKind::Connect,
+ None,
+ Some(CONNECT_BUTTON),
+ Some(CONNECT_HELP),
+ ),
+ phase => DesktopCover {
+ open_stream: phase == StreamPhase::NoSession,
+ ..cover(
+ DesktopCoverKind::Connecting,
+ Some(CONNECTING_TEXT),
+ None,
+ None,
+ )
+ },
+ }
+}
+
+/// How fresh the shells keep each Space's thumbnail (the notch tiles and
+/// the preview cover read the same one).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ThumbnailPolicy {
+ /// While the notch is open: every running Space, this often.
+ pub open_interval_ms: u64,
+ /// Otherwise (the app visible, not in Low Power Mode): a running Space
+ /// whose thumbnail is older than this gets a new one.
+ pub background_interval_ms: u64,
+ /// The long edge of a captured thumbnail, in pixels.
+ pub max_dimension: u32,
+ /// A thumbnail kept on disk longer than this is dropped at launch.
+ pub keep_ms: u64,
+}
+
+/// The thumbnail policy.
+pub fn thumbnail_policy() -> ThumbnailPolicy {
+ ThumbnailPolicy {
+ open_interval_ms: super::THUMBNAIL_INTERVAL_MS,
+ background_interval_ms: 90_000,
+ max_dimension: 320,
+ keep_ms: 7 * 24 * 60 * 60 * 1_000,
+ }
+}
+
+/// Whether a thumbnail captured at `captured_ms` (none: never) is due for a
+/// new one at `now_ms`, every `interval_ms`.
+pub fn thumbnail_due(captured_ms: Option<u64>, now_ms: u64, interval_ms: u64) -> bool {
+ captured_ms.is_none_or(|t| now_ms.saturating_sub(t) >= interval_ms)
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn input(stream: StreamPhase) -> DesktopCoverInput {
+ DesktopCoverInput {
+ can_stream: true,
+ preview_text: "Loading the desktop\u{2026}".into(),
+ auto_connect: true,
+ connect_requested: false,
+ stream,
+ }
+ }
+
+ #[test]
+ fn auto_connect_opens_the_stream_and_says_connecting() {
+ let c = desktop_cover(&input(StreamPhase::NoSession));
+ assert_eq!(c.kind, DesktopCoverKind::Connecting);
+ assert_eq!(c.text.as_deref(), Some(CONNECTING_TEXT));
+ assert!(c.open_stream && c.button.is_none());
+ // The session exists and opens: still connecting, nothing to open.
+ for phase in [StreamPhase::Idle, StreamPhase::Connecting] {
+ let c = desktop_cover(&input(phase));
+ assert_eq!(c.kind, DesktopCoverKind::Connecting);
+ assert!(!c.open_stream);
+ }
+ // The first frame: no cover.
+ assert_eq!(
+ desktop_cover(&input(StreamPhase::Streaming)).kind,
+ DesktopCoverKind::Stream
+ );
+ assert_eq!(
+ desktop_cover(&input(StreamPhase::Suspended)).kind,
+ DesktopCoverKind::Stream
+ );
+ }
+
+ #[test]
+ fn manual_connect_waits_for_the_button() {
+ let manual = DesktopCoverInput {
+ auto_connect: false,
+ ..input(StreamPhase::NoSession)
+ };
+ let c = desktop_cover(&manual);
+ assert_eq!(c.kind, DesktopCoverKind::Connect);
+ assert_eq!(c.button.as_deref(), Some(CONNECT_BUTTON));
+ assert_eq!(c.button_help.as_deref(), Some(CONNECT_HELP));
+ assert!(c.text.is_none() && !c.open_stream);
+ // Pressed: open it, connecting.
+ let pressed = DesktopCoverInput {
+ connect_requested: true,
+ ..manual.clone()
+ };
+ let c = desktop_cover(&pressed);
+ assert_eq!(c.kind, DesktopCoverKind::Connecting);
+ assert!(c.open_stream);
+ let c = desktop_cover(&DesktopCoverInput {
+ stream: StreamPhase::Connecting,
+ ..pressed.clone()
+ });
+ assert_eq!(
+ (c.kind, c.open_stream),
+ (DesktopCoverKind::Connecting, false)
+ );
+ let c = desktop_cover(&DesktopCoverInput {
+ stream: StreamPhase::Streaming,
+ ..pressed
+ });
+ assert_eq!(c.kind, DesktopCoverKind::Stream);
+ }
+
+ #[test]
+ fn a_space_that_cannot_stream_shows_its_line() {
+ for auto_connect in [true, false] {
+ let c = desktop_cover(&DesktopCoverInput {
+ can_stream: false,
+ preview_text: "Stopped".into(),
+ auto_connect,
+ ..input(StreamPhase::NoSession)
+ });
+ assert_eq!(c.kind, DesktopCoverKind::Status);
+ assert_eq!(c.text.as_deref(), Some("Stopped"));
+ assert!(c.button.is_none() && !c.open_stream && !c.retry);
+ }
+ }
+
+ #[test]
+ fn a_failed_stream_offers_try_again() {
+ let failed = desktop_cover(&input(StreamPhase::Failed));
+ assert_eq!(failed.kind, DesktopCoverKind::Status);
+ assert_eq!(failed.text.as_deref(), Some(FAILED_TEXT));
+ assert_eq!(failed.button.as_deref(), Some(RETRY_BUTTON));
+ assert!(!failed.retry && !failed.open_stream);
+ // Try again pressed: the shell starts the session again.
+ let c = desktop_cover(&DesktopCoverInput {
+ connect_requested: true,
+ ..input(StreamPhase::Failed)
+ });
+ assert!(c.retry);
+ }
+
+ #[test]
+ fn copy_has_no_em_dashes() {
+ for text in [
+ CONNECTING_TEXT,
+ CONNECT_BUTTON,
+ CONNECT_HELP,
+ FAILED_TEXT,
+ RETRY_BUTTON,
+ ] {
+ assert!(!text.contains('\u{2014}'), "{text}");
+ }
+ }
+
+ #[test]
+ fn thumbnails_refresh_on_the_policy() {
+ let p = thumbnail_policy();
+ assert_eq!(p.open_interval_ms, super::super::THUMBNAIL_INTERVAL_MS);
+ assert!((60_000..=120_000).contains(&p.background_interval_ms));
+ assert!(p.max_dimension <= 480);
+ assert!(thumbnail_due(None, 0, p.background_interval_ms));
+ assert!(!thumbnail_due(
+ Some(1_000),
+ 60_000,
+ p.background_interval_ms
+ ));
+ assert!(thumbnail_due(Some(1_000), 91_000, p.background_interval_ms));
+ // A clock that went backwards is not due.
+ assert!(!thumbnail_due(Some(5_000), 1_000, p.background_interval_ms));
+ }
+}
diff --git a/libs/cua/crates/cua-spaces-app-core/src/spaces/mod.rs b/libs/cua/crates/cua-spaces-app-core/src/spaces/mod.rs
index 7fed93b63e..e2a18cb583 100644
--- a/libs/cua/crates/cua-spaces-app-core/src/spaces/mod.rs
+++ b/libs/cua/crates/cua-spaces-app-core/src/spaces/mod.rs
@@ -3,12 +3,14 @@
//! Spaces: the SDK registry's rows as Spaces, their names, the MRU order,
//! the Space list state machine ([`roster`]) and the main window's sidebar
-//! and detail ([`sidebar`]) with its Stream section ([`stream`]).
+//! and detail ([`sidebar`]) with its Stream section ([`stream`]) and the
+//! cover over its live desktop ([`cover`]).
//!
//! Every location (Cua Cloud, this Mac, added by address, relay) arrives
//! through one `list_spaces` roster; the SDK owns lifecycle and the spacesd
//! handshake, this module only turns its rows into what the shells draw.
+pub mod cover;
pub mod creating;
pub mod roster;
pub mod sidebar;
diff --git a/libs/cua/crates/cua-spaces-ffi/src/app_core.rs b/libs/cua/crates/cua-spaces-ffi/src/app_core.rs
index 0e0cf33c6c..c106071bc9 100644
--- a/libs/cua/crates/cua-spaces-ffi/src/app_core.rs
+++ b/libs/cua/crates/cua-spaces-ffi/src/app_core.rs
@@ -168,6 +168,19 @@ pub fn app_space_detail_copy() -> AppDetailCopy {
core::spaces::sidebar::detail_copy()
}
+/// What a Space's preview card shows before (or instead of) its live
+/// desktop: "Connecting…", a Connect button, or the Space's own line.
+#[uniffi::export]
+pub fn app_desktop_cover(input: AppDesktopCoverInput) -> AppDesktopCover {
+ core::spaces::cover::desktop_cover(&input)
+}
+
+/// How fresh the shells keep each Space's thumbnail.
+#[uniffi::export]
+pub fn app_thumbnail_policy() -> AppThumbnailPolicy {
+ core::spaces::cover::thumbnail_policy()
+}
+
/// A Space's Stream section: the Desktop row, then one row per window.
#[uniffi::export]
pub fn app_stream_section(input: AppStreamSectionInput) -> AppStreamSection {
diff --git a/libs/cua/crates/cua-spaces-ffi/src/app_core_types.rs b/libs/cua/crates/cua-spaces-ffi/src/app_core_types.rs
index e866ebf41d..806bfc7c61 100644
--- a/libs/cua/crates/cua-spaces-ffi/src/app_core_types.rs
+++ b/libs/cua/crates/cua-spaces-ffi/src/app_core_types.rs
@@ -921,6 +921,90 @@ pub struct AppSpaceDetail {
pub power_error: Option<String>,
}
+/// Where the shell's stream session stands.
+pub type AppStreamPhase = core::spaces::cover::StreamPhase;
+#[uniffi::remote(Enum)]
+pub enum AppStreamPhase {
+ /// No session yet.
+ NoSession,
+ /// A session that has not started.
+ Idle,
+ /// Opening (no frame yet).
+ Connecting,
+ /// Frames arrive.
+ Streaming,
+ /// Paused by the Space (the stream view says why).
+ Suspended,
+ /// It could not open.
+ Failed,
+}
+
+/// What the cover is built from.
+pub type AppDesktopCoverInput = core::spaces::cover::DesktopCoverInput;
+#[uniffi::remote(Record)]
+pub struct AppDesktopCoverInput {
+ /// The detail's `can_stream`.
+ pub can_stream: bool,
+ /// The detail's `preview_text` (why it cannot stream).
+ pub preview_text: String,
+ /// Settings: "Connect to the desktop automatically".
+ pub auto_connect: bool,
+ /// Connect (or Try again) was pressed for this Space.
+ pub connect_requested: bool,
+ /// The shell's stream session.
+ pub stream: AppStreamPhase,
+}
+
+/// How the cover draws.
+pub type AppDesktopCoverKind = core::spaces::cover::DesktopCoverKind;
+#[uniffi::remote(Enum)]
+pub enum AppDesktopCoverKind {
+ /// No cover: the live desktop (or the stream view's own badge).
+ Stream,
+ /// The preview with "Connecting…".
+ Connecting,
+ /// The preview with a Connect button.
+ Connect,
+ /// The preview with a line (and maybe a button): the Space cannot
+ /// stream, or the stream failed.
+ Status,
+}
+
+/// The cover.
+pub type AppDesktopCover = core::spaces::cover::DesktopCover;
+#[uniffi::remote(Record)]
+pub struct AppDesktopCover {
+ /// How it draws.
+ pub kind: AppDesktopCoverKind,
+ /// The line, centered.
+ pub text: Option<String>,
+ /// A button under (or instead of) the line.
+ pub button: Option<String>,
+ /// Its tooltip.
+ pub button_help: Option<String>,
+ /// The shell opens a stream session now (none is open, and one is
+ /// wanted).
+ pub open_stream: bool,
+ /// The shell starts the open session again (Try again was pressed).
+ pub retry: bool,
+}
+
+/// How fresh the shells keep each Space's thumbnail (the notch tiles and
+/// the preview cover read the same one).
+pub type AppThumbnailPolicy = core::spaces::cover::ThumbnailPolicy;
+#[uniffi::remote(Record)]
+pub struct AppThumbnailPolicy {
+ /// While the notch is open: every running Space, this often.
+ pub open_interval_ms: u64,
+ /// Otherwise (the app visible, not in Low Power Mode): a running Space
+ /// whose thumbnail is older than this gets a new one.
+ pub background_interval_ms: u64,
+ /// The long edge of a captured thumbnail, in pixels.
+ pub max_dimension: u32,
+ /// A thumbnail kept on disk longer than this is dropped at launch.
+ pub keep_ms: u64,
+}
+
/// A display's size in physical pixels (the primary display of the list).
pub type AppStreamDisplay = core::spaces::stream::StreamDisplay;
#[uniffi::remote(Record)]
@@ -5597,6 +5681,10 @@ pub struct AppSettings {
/// longer shows them, nothing is revoked or wiped
/// ([`crate::keyvault::view::prune_dismissed`] forgets the gone ones).
pub dismissed_access: Vec<String>,
+ /// Settings, General: a running Space's desktop streams as soon as it
+ /// is opened (on by default); off, it waits for Connect
+ /// ([`crate::spaces::cover`]).
+ pub auto_connect: bool,
}
/// A pressed key combination.
@@ -5681,6 +5769,9 @@ pub struct AppSettingsInput {
/// The Keyvault's auto-wipe, once the broker told it (none: no
/// Keyvault section).
pub keyvault_auto_wipe: Option<bool>,
+ /// "Connect to the desktop automatically" (none: no row; a shell
+ /// without the preview cover leaves it out).
+ pub auto_connect: Option<bool>,
}
/// How a Settings row draws.
diff --git a/libs/cua/crates/cua-spaces/src/lib.rs b/libs/cua/crates/cua-spaces/src/lib.rs
index b36f7ffa6d..d066080099 100644
--- a/libs/cua/crates/cua-spaces/src/lib.rs
+++ b/libs/cua/crates/cua-spaces/src/lib.rs
@@ -78,6 +78,7 @@ pub mod routines;
pub mod services;
mod space;
mod spaces;
+pub mod thumbnails;
#[cfg(feature = "spaces-agents")]
pub mod agents;
diff --git a/libs/cua/crates/cua-spaces/src/spaces.rs b/libs/cua/crates/cua-spaces/src/spaces.rs
index 0b5c603ec7..d7b6e4890a 100644
--- a/libs/cua/crates/cua-spaces/src/spaces.rs
+++ b/libs/cua/crates/cua-spaces/src/spaces.rs
@@ -375,8 +375,10 @@ impl SpacesBuilder {
.join("Downloads")
.join("cua-spaces")
});
+ let thumbnails = crate::thumbnails::ThumbnailCache::in_home(&home);
Spaces {
inner: Arc::new(Inner {
+ thumbnails,
#[cfg(feature = "mcp")]
extensions: self.extensions,
#[cfg(feature = "spaces-agents")]
@@ -588,6 +590,8 @@ pub(crate) fn random_suffix() -> String {
pub(crate) struct Inner {
pub(crate) registry: Registry,
+ /// Every Space's latest thumbnail ([`crate::thumbnails`]).
+ pub(crate) thumbnails: crate::thumbnails::ThumbnailCache,
/// The registered extensions ([`crate::extension`]).
#[cfg(feature = "mcp")]
pub(crate) extensions: Vec<Arc<dyn crate::extension::SpacesExtension>>,
@@ -966,6 +970,7 @@ impl Spaces {
if !self.inner.registry.remove(&id.to_string())? && !matches!(id, SpaceId::Relay { .. }) {
return Err(Error::NotFound(id.to_string()));
}
+ self.inner.thumbnails.remove(&id.to_string());
Ok(info.unwrap_or_else(|| SpaceInfo {
id: id.to_string(),
name: id.short_name().into(),
@@ -2298,6 +2303,7 @@ impl Spaces {
pub async fn delete(&self, space: &str) -> Result<String> {
let id = self.resolve(space)?;
self.drop_connection(&id).await;
+ self.inner.thumbnails.remove(&id.to_string());
// A Space in your cloud: its sandbox goes, with everything the
// sandbox layer made for it (instance, relay machine).
if let Some(sandbox) = self.cloud_sandbox_of(&id.to_string())? {
@@ -2404,6 +2410,113 @@ impl Spaces {
}
}
+ // ---------------------------------------------------------- thumbnails
+
+ /// The thumbnail cache every client of this runtime shares.
+ pub fn thumbnails(&self) -> &crate::thumbnails::ThumbnailCache {
+ &self.inner.thumbnails
+ }
+
+ /// The Space's latest thumbnail (a small JPEG of its primary display):
+ /// the cached one when it is younger than `max_age` (none: any age),
+ /// else a fresh capture through cua-spacesd, kept for the next caller.
+ /// When the capture fails, the older cached one (its `captured_at`
+ /// says how old); with nothing cached, the capture's error. Asking
+ /// keeps [`Self::refresh_thumbnails`] going ([`crate::thumbnails`]).
+ pub async fn thumbnail(
+ &self,
+ space: &str,
+ max_age: Option<Duration>,
+ ) -> Result<crate::thumbnails::Thumbnail> {
+ let id = self.resolve(space)?.to_string();
+ let cache = &self.inner.thumbnails;
+ cache.note_interest(std::time::Instant::now());
+ let cached = cache.get(&id);
+ if let Some(t) = &cached
+ && t.is_fresh(max_age, SystemTime::now())
+ {
+ return Ok(t.clone());
+ }
+ match self.capture_thumbnail(&id).await {
+ Ok(t) => Ok(t),
+ Err(e) => cached.ok_or(e),
+ }
+ }
+
+ /// Captures and caches the Space's thumbnail now.
+ async fn capture_thumbnail(&self, id: &str) -> Result<crate::thumbnails::Thumbnail> {
+ use crate::thumbnails::{MAX_DIMENSION, QUALITY, Thumbnail};
+ let space = self.space(id).await?;
+ let shot = space
+ .spacesd()?
+ .screenshot(cua_spacesd_client::ScreenshotOptions {
+ display: None,
+ format: pb::ImageFormat::Jpeg,
+ quality: QUALITY,
+ max_dimension: MAX_DIMENSION,
+ include_cursor: false,
+ })
+ .await?;
+ let t = Thumbnail {
+ image: shot.image.to_vec(),
+ format: match shot.format {
+ pb::ImageFormat::Png => "png",
+ pb::ImageFormat::Webp => "webp",
+ _ => "jpeg",
+ }
+ .into(),
+ width: shot.width,
+ height: shot.height,
+ captured_at: SystemTime::now(),
+ };
+ self.inner.thumbnails.put(id, t.clone());
+ Ok(t)
+ }
+
+ /// One background pass over the thumbnails, while someone asked for
+ /// one recently: forgets those of Spaces that are gone, then captures
+ /// each running Space's that is due (older than
+ /// [`crate::thumbnails::BACKGROUND_INTERVAL`]). Returns how many it
+ /// captured. A Space that does not answer is skipped quietly.
+ pub async fn refresh_thumbnails(&self) -> usize {
+ let cache = &self.inner.thumbnails;
+ if !cache.interested(std::time::Instant::now()) {
+ return 0;
+ }
+ let Ok(spaces) = self.list() else { return 0 };
+ cache.retain(&spaces.iter().map(|s| s.id.clone()).collect());
+ let now = SystemTime::now();
+ let mut captured = 0;
+ for info in spaces {
+ let off = matches!(info.power_state.as_str(), "suspended" | "stopped");
+ if off || info.spacesd_version.is_empty() || !cache.due(&info.id, now) {
+ continue;
+ }
+ match tokio::time::timeout(Duration::from_secs(10), self.capture_thumbnail(&info.id))
+ .await
+ {
+ Ok(Ok(_)) => captured += 1,
+ Ok(Err(e)) => tracing::debug!(space = %info.id, error = %e, "thumbnail skipped"),
+ Err(_) => tracing::debug!(space = %info.id, "thumbnail timed out"),
+ }
+ }
+ captured
+ }
+
+ /// Runs [`Self::refresh_thumbnails`] every
+ /// [`crate::thumbnails::REFRESH_TICK`] until the runtime is dropped
+ /// (the daemon starts it once).
+ pub fn spawn_thumbnail_refresh(&self) -> tokio::task::JoinHandle<()> {
+ let weak = Arc::downgrade(&self.inner);
+ tokio::spawn(async move {
+ loop {
+ tokio::time::sleep(crate::thumbnails::REFRESH_TICK).await;
+ let Some(inner) = weak.upgrade() else { return };
+ Spaces { inner }.refresh_thumbnails().await;
+ }
+ })
+ }
+
// --------------------------------------------------------------- power
/// [`SpaceInfo::power`] and [`SpaceInfo::power_state`] of the Space
diff --git a/libs/cua/crates/cua-spaces/src/thumbnails.rs b/libs/cua/crates/cua-spaces/src/thumbnails.rs
new file mode 100644
index 0000000000..fba83ab5b0
--- /dev/null
+++ b/libs/cua/crates/cua-spaces/src/thumbnails.rs
@@ -0,0 +1,411 @@
+//! Space thumbnails, cached once for every client on this machine (the
+//! Spaces apps' notch tiles and previews, the CLI, SDK scripts): the latest
+//! small JPEG of each Space's primary display, in memory and on disk under
+//! `$CUA_HOME/cache/thumbnails`.
+//!
+//! - [`crate::Spaces::thumbnail`] answers from the cache when the entry is
+//! younger than the caller's `max_age`, else captures a fresh one through
+//! cua-spacesd (and falls back to the older entry when that fails).
+//! - Asking marks interest. While someone asked within
+//! [`INTEREST_WINDOW`], [`crate::Spaces::refresh_thumbnails`] (the
+//! daemon runs it every [`REFRESH_TICK`]) captures each running Space
+//! whose entry is older than [`BACKGROUND_INTERVAL`], so a preview is
+//! seldom more than a couple of minutes old. Nobody asking: no guest load.
+//! - Entries survive restarts (`<stem>.jpg` plus `<stem>.json`, 0600), a
+//! deleted or forgotten Space's entry goes with it, and the disk use is
+//! capped ([`DISK_BYTES`]): the oldest captures go first. Writes go
+//! through the cua-home test guard, so a test never writes the user's
+//! real `~/.cua`.
+
+use sha2::{Digest, Sha256};
+use std::collections::{HashMap, HashSet};
+use std::path::{Path, PathBuf};
+use std::sync::Mutex;
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+
+/// A running Space's thumbnail is captured again once it is this old
+/// (while someone is interested).
+pub const BACKGROUND_INTERVAL: Duration = Duration::from_secs(90);
+/// How long one request keeps the background refresh going.
+pub const INTEREST_WINDOW: Duration = Duration::from_secs(10 * 60);
+/// How often the daemon checks which thumbnails are due.
+pub const REFRESH_TICK: Duration = Duration::from_secs(30);
+/// Long edge of a captured thumbnail, pixels.
+pub const MAX_DIMENSION: u32 = 320;
+/// JPEG quality of a captured thumbnail.
+pub const QUALITY: u32 = 70;
+/// Disk cap for the whole cache.
+pub const DISK_BYTES: u64 = 32 * 1024 * 1024;
+
+/// One Space's latest thumbnail.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct Thumbnail {
+ /// Encoded image.
+ pub image: Vec<u8>,
+ /// `jpeg` (or `png`).
+ pub format: String,
+ /// Pixel width.
+ pub width: u32,
+ /// Pixel height.
+ pub height: u32,
+ /// When it was captured.
+ pub captured_at: SystemTime,
+}
+
+impl Thumbnail {
+ /// Whether it is younger than `max_age` at `now` (none: any age).
+ pub fn is_fresh(&self, max_age: Option<Duration>, now: SystemTime) -> bool {
+ match max_age {
+ None => true,
+ Some(max) => now
+ .duration_since(self.captured_at)
+ .map(|age| age < max)
+ // Captured "in the future" (the clock moved back): fresh.
+ .unwrap_or(true),
+ }
+ }
+
+ fn ms(&self) -> u64 {
+ self.captured_at
+ .duration_since(UNIX_EPOCH)
+ .map(|d| d.as_millis() as u64)
+ .unwrap_or(0)
+ }
+}
+
+#[derive(serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct Meta {
+ space: String,
+ format: String,
+ width: u32,
+ height: u32,
+ captured_at_ms: u64,
+}
+
+#[derive(Default)]
+struct State {
+ entries: HashMap<String, Thumbnail>,
+ loaded: bool,
+ interest: Option<Instant>,
+}
+
+/// The cache. Cheap to share behind the runtime's `Arc`.
+pub struct ThumbnailCache {
+ dir: Option<PathBuf>,
+ disk_bytes: u64,
+ state: Mutex<State>,
+}
+
+impl std::fmt::Debug for ThumbnailCache {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.debug_struct("ThumbnailCache")
+ .field("dir", &self.dir)
+ .finish()
+ }
+}
+
+/// The file stem of a Space id (hex of its SHA-256, 32 chars).
+fn stem(space: &str) -> String {
+ hex::encode(&Sha256::digest(space.as_bytes())[..16])
+}
+
+impl ThumbnailCache {
+ /// A cache kept in `dir` (none: memory only), capped at `disk_bytes`.
+ pub fn new(dir: Option<PathBuf>, disk_bytes: u64) -> Self {
+ Self {
+ dir,
+ disk_bytes,
+ state: Mutex::new(State::default()),
+ }
+ }
+
+ /// The cache under the cua home `home` (`cache/thumbnails`).
+ pub fn in_home(home: &Path) -> Self {
+ Self::new(Some(home.join("cache").join("thumbnails")), DISK_BYTES)
+ }
+
+ /// Where it keeps its files.
+ pub fn dir(&self) -> Option<&Path> {
+ self.dir.as_deref()
+ }
+
+ fn state(&self) -> std::sync::MutexGuard<'_, State> {
+ let mut s = self.state.lock().expect("thumbnail cache");
+ if !s.loaded {
+ s.loaded = true;
+ if let Some(dir) = &self.dir {
+ s.entries = load(dir);
+ }
+ }
+ s
+ }
+
+ /// The Space's cached thumbnail, of any age.
+ pub fn get(&self, space: &str) -> Option<Thumbnail> {
+ self.state().entries.get(space).cloned()
+ }
+
+ /// Every cached Space id.
+ pub fn spaces(&self) -> Vec<String> {
+ self.state().entries.keys().cloned().collect()
+ }
+
+ /// Keeps `t` as the Space's thumbnail (on disk too), then evicts the
+ /// oldest captures past the disk cap.
+ pub fn put(&self, space: &str, t: Thumbnail) {
+ let mut s = self.state();
+ if let Some(dir) = &self.dir
+ && let Err(e) = write(dir, space, &t)
+ {
+ tracing::debug!(space, error = %e, "thumbnail not written");
+ }
+ s.entries.insert(space.to_string(), t);
+ self.enforce_cap(&mut s);
+ }
+
+ /// Forgets the Space's thumbnail (a deleted or forgotten Space).
+ pub fn remove(&self, space: &str) {
+ let mut s = self.state();
+ s.entries.remove(space);
+ if let Some(dir) = &self.dir {
+ unlink(dir, space);
+ }
+ }
+
+ /// Forgets every thumbnail of a Space not in `keep`.
+ pub fn retain(&self, keep: &HashSet<String>) {
+ let gone: Vec<String> = self
+ .state()
+ .entries
+ .keys()
+ .filter(|k| !keep.contains(*k))
+ .cloned()
+ .collect();
+ for id in gone {
+ self.remove(&id);
+ }
+ }
+
+ /// Someone asked for a thumbnail at `now`.
+ pub fn note_interest(&self, now: Instant) {
+ self.state.lock().expect("thumbnail cache").interest = Some(now);
+ }
+
+ /// Whether someone asked within [`INTEREST_WINDOW`] of `now`.
+ pub fn interested(&self, now: Instant) -> bool {
+ self.state
+ .lock()
+ .expect("thumbnail cache")
+ .interest
+ .is_some_and(|t| now.saturating_duration_since(t) < INTEREST_WINDOW)
+ }
+
+ /// Whether the Space's thumbnail is due for a background capture at
+ /// `now` (none yet, or older than [`BACKGROUND_INTERVAL`]).
+ pub fn due(&self, space: &str, now: SystemTime) -> bool {
+ self.get(space)
+ .is_none_or(|t| !t.is_fresh(Some(BACKGROUND_INTERVAL), now))
+ }
+
+ fn enforce_cap(&self, s: &mut State) {
+ let mut total: u64 = s.entries.values().map(|t| t.image.len() as u64).sum();
+ if total <= self.disk_bytes {
+ return;
+ }
+ let mut by_age: Vec<(u64, String)> =
+ s.entries.iter().map(|(k, t)| (t.ms(), k.clone())).collect();
+ by_age.sort();
+ for (_, id) in by_age {
+ if total <= self.disk_bytes {
+ break;
+ }
+ if let Some(t) = s.entries.remove(&id) {
+ total -= t.image.len() as u64;
+ if let Some(dir) = &self.dir {
+ unlink(dir, &id);
+ }
+ }
+ }
+ }
+}
+
+fn load(dir: &Path) -> HashMap<String, Thumbnail> {
+ let mut out = HashMap::new();
+ let Ok(read) = std::fs::read_dir(dir) else {
+ return out;
+ };
+ for entry in read.flatten() {
+ let path = entry.path();
+ if path.extension().and_then(|e| e.to_str()) != Some("json") {
+ continue;
+ }
+ let Some(meta) = std::fs::read(&path)
+ .ok()
+ .and_then(|b| serde_json::from_slice::<Meta>(&b).ok())
+ else {
+ continue;
+ };
+ let Ok(image) = std::fs::read(path.with_extension("img")) else {
+ continue;
+ };
+ out.insert(
+ meta.space,
+ Thumbnail {
+ image,
+ format: meta.format,
+ width: meta.width,
+ height: meta.height,
+ captured_at: UNIX_EPOCH + Duration::from_millis(meta.captured_at_ms),
+ },
+ );
+ }
+ out
+}
+
+fn write(dir: &Path, space: &str, t: &Thumbnail) -> std::io::Result<()> {
+ let base = dir.join(stem(space));
+ cua_home::guard_write(&base)?;
+ std::fs::create_dir_all(dir)?;
+ let meta = Meta {
+ space: space.to_string(),
+ format: t.format.clone(),
+ width: t.width,
+ height: t.height,
+ captured_at_ms: t.ms(),
+ };
+ // The image first: a reader that finds the metadata finds its image.
+ cua_home::write_private(&base.with_extension("img"), &t.image)?;
+ cua_home::write_private(
+ &base.with_extension("json"),
+ &serde_json::to_vec(&meta).map_err(std::io::Error::other)?,
+ )
+}
+
+fn unlink(dir: &Path, space: &str) {
+ let base = dir.join(stem(space));
+ if cua_home::guard_write(&base).is_err() {
+ return;
+ }
+ let _ = std::fs::remove_file(base.with_extension("json"));
+ let _ = std::fs::remove_file(base.with_extension("img"));
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn shot(bytes: usize, at_ms: u64) -> Thumbnail {
+ Thumbnail {
+ image: vec![7; bytes],
+ format: "jpeg".into(),
+ width: 320,
+ height: 200,
+ captured_at: UNIX_EPOCH + Duration::from_millis(at_ms),
+ }
+ }
+
+ fn temp(name: &str) -> PathBuf {
+ let dir = std::env::temp_dir().join(format!(
+ "cua-thumbnails-{name}-{}-{}",
+ std::process::id(),
+ rand::random::<u32>()
+ ));
+ let _ = std::fs::remove_dir_all(&dir);
+ dir
+ }
+
+ #[test]
+ fn freshness_follows_max_age() {
+ let t = shot(10, 1_000_000);
+ let now = UNIX_EPOCH + Duration::from_millis(1_060_000);
+ assert!(t.is_fresh(None, now), "no max age: any age");
+ assert!(t.is_fresh(Some(Duration::from_secs(90)), now));
+ assert!(!t.is_fresh(Some(Duration::from_secs(60)), now));
+ assert!(
+ !t.is_fresh(Some(Duration::ZERO), now),
+ "zero: always capture"
+ );
+ // A clock that moved back: still fresh.
+ assert!(t.is_fresh(Some(Duration::from_secs(1)), UNIX_EPOCH));
+ let cache = ThumbnailCache::new(None, DISK_BYTES);
+ assert!(cache.due("local:a", now), "nothing cached: due");
+ cache.put("local:a", t);
+ assert!(!cache.due("local:a", now));
+ assert!(cache.due("local:a", now + BACKGROUND_INTERVAL));
+ }
+
+ #[test]
+ fn interest_lapses_after_the_window() {
+ let cache = ThumbnailCache::new(None, DISK_BYTES);
+ let t0 = Instant::now();
+ assert!(!cache.interested(t0), "nobody asked");
+ cache.note_interest(t0);
+ assert!(cache.interested(t0 + Duration::from_secs(60)));
+ assert!(!cache.interested(t0 + INTEREST_WINDOW));
+ }
+
+ #[test]
+ fn entries_persist_across_a_restart() {
+ let dir = temp("persist");
+ let cache = ThumbnailCache::new(Some(dir.clone()), DISK_BYTES);
+ cache.put("local:a", shot(100, 5_000));
+ cache.put("relay:b", shot(50, 6_000));
+ drop(cache);
+ let again = ThumbnailCache::new(Some(dir.clone()), DISK_BYTES);
+ assert_eq!(again.get("local:a"), Some(shot(100, 5_000)));
+ assert_eq!(again.get("relay:b"), Some(shot(50, 6_000)));
+ // Removed: gone from disk too.
+ again.remove("relay:b");
+ let third = ThumbnailCache::new(Some(dir.clone()), DISK_BYTES);
+ assert_eq!(third.get("relay:b"), None);
+ assert!(third.get("local:a").is_some());
+ // Files are owner-only.
+ #[cfg(unix)]
+ {
+ use std::os::unix::fs::PermissionsExt;
+ let img = dir.join(stem("local:a")).with_extension("img");
+ let mode = std::fs::metadata(img).unwrap().permissions().mode();
+ assert_eq!(mode & 0o077, 0, "0600");
+ }
+ let _ = std::fs::remove_dir_all(dir);
+ }
+
+ #[test]
+ fn deleted_spaces_and_the_oldest_past_the_cap_are_evicted() {
+ let dir = temp("evict");
+ let cache = ThumbnailCache::new(Some(dir.clone()), 250);
+ cache.put("a", shot(100, 1_000));
+ cache.put("b", shot(100, 2_000));
+ cache.put("c", shot(100, 3_000));
+ // 300 bytes > 250: the oldest (a) went.
+ assert_eq!(cache.get("a"), None);
+ assert!(cache.get("b").is_some() && cache.get("c").is_some());
+ // A new capture of b makes c the oldest.
+ cache.put("b", shot(100, 4_000));
+ cache.put("d", shot(100, 5_000));
+ assert_eq!(cache.get("c"), None);
+ // Spaces that no longer exist go.
+ cache.retain(&HashSet::from(["d".to_string()]));
+ assert_eq!(cache.spaces(), vec!["d".to_string()]);
+ let reloaded = ThumbnailCache::new(Some(dir.clone()), 250);
+ assert_eq!(reloaded.spaces(), vec!["d".to_string()]);
+ let _ = std::fs::remove_dir_all(dir);
+ }
+
+ #[test]
+ fn damaged_files_are_skipped() {
+ let dir = temp("damaged");
+ std::fs::create_dir_all(&dir).unwrap();
+ std::fs::write(dir.join("x.json"), b"{nope").unwrap();
+ std::fs::write(
+ dir.join("y.json"),
+ br#"{"space":"y","format":"jpeg","width":1,"height":1,"capturedAtMs":1}"#,
+ )
+ .unwrap();
+ // y has no image: skipped.
+ let cache = ThumbnailCache::new(Some(dir.clone()), DISK_BYTES);
+ assert!(cache.spaces().is_empty());
+ let _ = std::fs::remove_dir_all(dir);
+ }
+}
diff --git a/libs/cua/crates/cua-spaces/tests/thumbnails.rs b/libs/cua/crates/cua-spaces/tests/thumbnails.rs
new file mode 100644
index 0000000000..3d1debfd9c
--- /dev/null
+++ b/libs/cua/crates/cua-spaces/tests/thumbnails.rs
@@ -0,0 +1,97 @@
+//! The Spaces runtime's thumbnail cache, as the daemon serves it
+//! (`SpaceService.GetSpaceThumbnail`): cached answers within `max_age`,
+//! the older image when a fresh capture fails, persistence across a
+//! restart of the runtime, and the background pass's eviction and
+//! interest gate. Hermetic: a temp cua home, no Space ever answers.
+
+use cua_spaces::Spaces;
+use cua_spaces::thumbnails::Thumbnail;
+use std::time::{Duration, Instant, SystemTime};
+
+const ID: &str = "direct:127.0.0.1:9";
+
+fn spaces(home: &std::path::Path) -> Spaces {
+ Spaces::builder()
+ .home(home)
+ .sandboxes(
+ cua_sandbox_core::Sandboxes::builder()
+ .state_dir(home.join("sandboxes"))
+ .build(),
+ )
+ .build()
+}
+
+fn shot(age: Duration) -> Thumbnail {
+ Thumbnail {
+ image: vec![0xff, 0xd8, 0xff, 0xd9],
+ format: "jpeg".into(),
+ width: 320,
+ height: 200,
+ captured_at: SystemTime::now() - age,
+ }
+}
+
+#[tokio::test]
+async fn cached_within_max_age_else_the_older_one_when_capture_fails() {
+ let home = tempfile::tempdir().unwrap();
+ let s = spaces(home.path());
+ // Nothing cached and nothing answers: the capture's error.
+ assert!(s.thumbnail(ID, None).await.is_err());
+
+ let cached = shot(Duration::from_secs(30));
+ s.thumbnails().put(ID, cached.clone());
+ // Younger than max_age (or any age): at once, no capture.
+ assert_eq!(s.thumbnail(ID, None).await.unwrap(), cached);
+ assert_eq!(
+ s.thumbnail(ID, Some(Duration::from_secs(60)))
+ .await
+ .unwrap(),
+ cached
+ );
+ // Older than max_age: a capture is tried; it fails (the Space is not
+ // registered), so the older image comes back with its timestamp.
+ let stale = s.thumbnail(ID, Some(Duration::ZERO)).await.unwrap();
+ assert_eq!(stale.captured_at, cached.captured_at);
+ // Asking marked interest.
+ assert!(s.thumbnails().interested(Instant::now()));
+}
+
+#[tokio::test]
+async fn the_cache_survives_a_restart_under_the_cua_home() {
+ let home = tempfile::tempdir().unwrap();
+ let t = shot(Duration::from_secs(5));
+ spaces(home.path()).thumbnails().put(ID, t.clone());
+ let dir = home.path().join("cache").join("thumbnails");
+ assert!(dir.is_dir(), "kept under <cua home>/cache/thumbnails");
+ let again = spaces(home.path()).thumbnail(ID, None).await.unwrap();
+ assert_eq!(
+ (&again.image, again.width, again.height),
+ (&t.image, t.width, t.height)
+ );
+ // Kept to the millisecond.
+ let ms = |t: &Thumbnail| {
+ t.captured_at
+ .duration_since(SystemTime::UNIX_EPOCH)
+ .unwrap()
+ .as_millis()
+ };
+ assert_eq!(ms(&again), ms(&t));
+}
+
+#[tokio::test]
+async fn the_background_pass_needs_interest_and_evicts_gone_spaces() {
+ let home = tempfile::tempdir().unwrap();
+ let s = spaces(home.path());
+ s.thumbnails().put(ID, shot(Duration::from_secs(5)));
+ // Nobody asked: nothing happens (no guest load, nothing evicted).
+ assert_eq!(s.refresh_thumbnails().await, 0);
+ assert!(s.thumbnails().get(ID).is_some());
+ // Someone asked: the Space is not in the registry, so its image goes.
+ s.thumbnails().note_interest(Instant::now());
+ assert_eq!(s.refresh_thumbnails().await, 0);
+ assert!(s.thumbnails().get(ID).is_none());
+ assert!(
+ spaces(home.path()).thumbnails().get(ID).is_none(),
+ "on disk too"
+ );
+}
diff --git a/libs/cua/kotlin/src/main/kotlin/ai/cua/sdk/cua_sdk.kt b/libs/cua/kotlin/src/main/kotlin/ai/cua/sdk/cua_sdk.kt
index 70844a9c17..3ab9b0d58b 100644
--- a/libs/cua/kotlin/src/main/kotlin/ai/cua/sdk/cua_sdk.kt
+++ b/libs/cua/kotlin/src/main/kotlin/ai/cua/sdk/cua_sdk.kt
@@ -1315,6 +1315,8 @@ external fun uniffi_cua_sdk_checksum_method_space_teleport(
): Short
external fun uniffi_cua_sdk_checksum_method_space_teleport_manifest(
): Short
+external fun uniffi_cua_sdk_checksum_method_space_thumbnail(
+): Short
external fun uniffi_cua_sdk_checksum_method_space_unshare(
): Short
external fun uniffi_cua_sdk_checksum_method_space_upload(
@@ -2221,6 +2223,8 @@ external fun uniffi_cua_sdk_fn_method_space_teleport(`ptr`: Long,`app`: RustBuff
): Long
external fun uniffi_cua_sdk_fn_method_space_teleport_manifest(`ptr`: Long,`app`: RustBuffer.ByValue,`scope`: RustBuffer.ByValue,
): Long
+external fun uniffi_cua_sdk_fn_method_space_thumbnail(`ptr`: Long,`maxAgeMs`: RustBuffer.ByValue,
+): Long
external fun uniffi_cua_sdk_fn_method_space_unshare(`ptr`: Long,`who`: RustBuffer.ByValue,
): Long
external fun uniffi_cua_sdk_fn_method_space_upload(`ptr`: Long,`localPath`: RustBuffer.ByValue,`dest`: RustBuffer.ByValue,
@@ -3593,7 +3597,7 @@ private fun uniffiCheckApiChecksums(lib: IntegrityCheckingUniffiLib) {
if (lib.uniffi_cua_sdk_checksum_method_space_request_site_login() != 2223.toShort()) {
throw RuntimeException("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
}
- if (lib.uniffi_cua_sdk_checksum_method_space_screenshot() != 9108.toShort()) {
+ if (lib.uniffi_cua_sdk_checksum_method_space_screenshot() != 41142.toShort()) {
throw RuntimeException("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
}
if (lib.uniffi_cua_sdk_checksum_method_space_send_file() != 29056.toShort()) {
@@ -3629,6 +3633,9 @@ private fun uniffiCheckApiChecksums(lib: IntegrityCheckingUniffiLib) {
if (lib.uniffi_cua_sdk_checksum_method_space_teleport_manifest() != 31596.toShort()) {
throw RuntimeException("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
}
+ if (lib.uniffi_cua_sdk_checksum_method_space_thumbnail() != 10979.toShort()) {
+ throw RuntimeException("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
+ }
if (lib.uniffi_cua_sdk_checksum_method_space_unshare() != 58172.toShort()) {
throw RuntimeException("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
}
@@ -16162,10 +16169,10 @@ public interface SpaceInterface {
suspend fun `requestSiteLogin`(`url`: kotlin.String, `options`: SiteLoginOptions?): SiteLoginReport
/**
- * Captures the Space's display (the app's tile thumbnails): PNG at
- * full size on the primary display unless `options` say otherwise.
- * Fails with `CapabilityMissing` (`spacesd`) when the image runs no
- * cua-spacesd.
+ * Captures the Space's display: PNG at full size on the primary
+ * display unless `options` say otherwise (for a small preview,
+ * [`Space::thumbnail`] reads the shared cache instead). Fails with
+ * `CapabilityMissing` (`spacesd`) when the image runs no cua-spacesd.
*/
suspend fun `screenshot`(`options`: ScreenshotOptions?): Screenshot
@@ -16248,6 +16255,17 @@ public interface SpaceInterface {
*/
suspend fun `teleportManifest`(`app`: kotlin.String, `scope`: kotlin.String?): TeleportManifest
+ /**
+ * The Space's latest thumbnail (a small JPEG of its primary display)
+ * from the cache every client on this machine shares: returned at
+ * once when it is younger than `max_age_ms` (unset: any age), else
+ * captured fresh through cua-spacesd and kept for the next caller.
+ * When that capture fails, the older one comes back (`captured_at_ms`
+ * says how old). Asking keeps the daemon refreshing running Spaces'
+ * thumbnails in the background for a while (about every 90 s).
+ */
+ suspend fun `thumbnail`(`maxAgeMs`: kotlin.ULong?): SpaceThumbnail
+
/**
* Stops sharing this Space with `who` at once, or with everyone when
* `who` is `None`.
@@ -16975,10 +16993,10 @@ open class Space: Disposable, AutoCloseable, SpaceInterface
/**
- * Captures the Space's display (the app's tile thumbnails): PNG at
- * full size on the primary display unless `options` say otherwise.
- * Fails with `CapabilityMissing` (`spacesd`) when the image runs no
- * cua-spacesd.
+ * Captures the Space's display: PNG at full size on the primary
+ * display unless `options` say otherwise (for a small preview,
+ * [`Space::thumbnail`] reads the shared cache instead). Fails with
+ * `CapabilityMissing` (`spacesd`) when the image runs no cua-spacesd.
*/
@Throws(CuaException::class)
@Suppress("ASSIGNED_BUT_NEVER_ACCESSED_VARIABLE")
@@ -17274,6 +17292,36 @@ open class Space: Disposable, AutoCloseable, SpaceInterface
}
+ /**
+ * The Space's latest thumbnail (a small JPEG of its primary display)
+ * from the cache every client on this machine shares: returned at
+ * once when it is younger than `max_age_ms` (unset: any age), else
+ * captured fresh through cua-spacesd and kept for the next caller.
+ * When that capture fails, the older one comes back (`captured_at_ms`
+ * says how old). Asking keeps the daemon refreshing running Spaces'
+ * thumbnails in the background for a while (about every 90 s).
+ */
+ @Throws(CuaException::class)
+ @Suppress("ASSIGNED_BUT_NEVER_ACCESSED_VARIABLE")
+ override suspend fun `thumbnail`(`maxAgeMs`: kotlin.ULong?) : SpaceThumbnail {
+ return uniffiRustCallAsync(
+ callWithHandle { uniffiHandle ->
+ UniffiLib.uniffi_cua_sdk_fn_method_space_thumbnail(
+ uniffiHandle,
+ FfiConverterOptionalULong.lower(`maxAgeMs`),
+ )
+ },
+ { future, callback, continuation -> UniffiLib.ffi_cua_sdk_rust_future_poll_rust_buffer(future, callback, continuation) },
+ { future, continuation -> UniffiLib.ffi_cua_sdk_rust_future_complete_rust_buffer(future, continuation) },
+ { future -> UniffiLib.ffi_cua_sdk_rust_future_free_rust_buffer(future) },
+ // lift function
+ { FfiConverterTypeSpaceThumbnail.lift(it) },
+ // Error FFI converter
+ CuaException.ErrorHandler,
+ )
+ }
+
+
/**
* Stops sharing this Space with `who` at once, or with everyone when
* `who` is `None`.
@@ -36166,6 +36214,78 @@ public object FfiConverterTypeSpaceStreamTicket: FfiConverterRustBuffer<SpaceStr
+/**
+ * A Space's latest thumbnail, from the cache every client on this machine
+ * shares ([`crate::native::spaces::Space::thumbnail`]).
+ */
+data class SpaceThumbnail (
+ /**
+ * Encoded image (a small JPEG of the primary display).
+ */
+ var `image`: kotlin.ByteArray
+ ,
+ /**
+ * Encoding.
+ */
+ var `format`: ImageFormat
+ ,
+ /**
+ * Pixel width.
+ */
+ var `width`: kotlin.UInt
+ ,
+ /**
+ * Pixel height.
+ */
+ var `height`: kotlin.UInt
+ ,
+ /**
+ * When it was captured, Unix milliseconds.
+ */
+ var `capturedAtMs`: kotlin.ULong
+
+){
+
+
+
+
+
+ companion object
+}
+
+/**
+ * @suppress
+ */
+public object FfiConverterTypeSpaceThumbnail: FfiConverterRustBuffer<SpaceThumbnail> {
+ override fun read(buf: ByteBuffer): SpaceThumbnail {
+ return SpaceThumbnail(
+ FfiConverterByteArray.read(buf),
+ FfiConverterTypeImageFormat.read(buf),
+ FfiConverterUInt.read(buf),
+ FfiConverterUInt.read(buf),
+ FfiConverterULong.read(buf),
+ )
+ }
+
+ override fun allocationSize(value: SpaceThumbnail) = (
+ FfiConverterByteArray.allocationSize(value.`image`) +
+ FfiConverterTypeImageFormat.allocationSize(value.`format`) +
+ FfiConverterUInt.allocationSize(value.`width`) +
+ FfiConverterUInt.allocationSize(value.`height`) +
+ FfiConverterULong.allocationSize(value.`capturedAtMs`)
+ )
+
+ override fun write(value: SpaceThumbnail, buf: ByteBuffer) {
+ FfiConverterByteArray.write(value.`image`, buf)
+ FfiConverterTypeImageFormat.write(value.`format`, buf)
+ FfiConverterUInt.write(value.`width`, buf)
+ FfiConverterUInt.write(value.`height`, buf)
+ FfiConverterULong.write(value.`capturedAtMs`, buf)
+ }
+}
+
+
+
/**
* A tool of a Space's MCP service.
*/
diff --git a/libs/cua/proto/cua/daemon/v1/spaces.proto b/libs/cua/proto/cua/daemon/v1/spaces.proto
index 769773ff4d..6177a994d5 100644
--- a/libs/cua/proto/cua/daemon/v1/spaces.proto
+++ b/libs/cua/proto/cua/daemon/v1/spaces.proto
@@ -80,6 +80,13 @@ service SpaceService {
// wizard's Run on menu). One that does not answer is listed offline when
// it provided a Space before.
rpc ListHosts(ListHostsRequest) returns (ListHostsResponse);
+ // The Space's latest thumbnail (a small JPEG of its primary display)
+ // from the daemon's cache, which every client on this machine shares:
+ // the cached image when it is younger than `max_age`, else a fresh
+ // capture through cua-spacesd (the cached one again, with its older
+ // `captured_at`, when the capture fails). Asking keeps the daemon
+ // refreshing running Spaces' thumbnails in the background for a while.
+ rpc GetSpaceThumbnail(GetSpaceThumbnailRequest) returns (GetSpaceThumbnailResponse);
}
// A registered Space.
@@ -543,3 +550,26 @@ message ListHostsResponse {
// In order: relay hosts, then direct ones.
repeated SpacesHost hosts = 1;
}
+
+// Request for `SpaceService.GetSpaceThumbnail`.
+message GetSpaceThumbnailRequest {
+ // Space.
+ string space = 1;
+ // How old a cached thumbnail may be (unset: any age; zero: always
+ // capture).
+ google.protobuf.Duration max_age = 2;
+}
+
+// Response for `SpaceService.GetSpaceThumbnail`.
+message GetSpaceThumbnailResponse {
+ // Encoded image.
+ bytes image = 1;
+ // "jpeg".
+ string format = 2;
+ // Pixel width.
+ uint32 width = 3;
+ // Pixel height.
+ uint32 height = 4;
+ // When it was captured.
+ google.protobuf.Timestamp captured_at = 5;
+}
diff --git a/libs/cua/python/src/cua/_native.py b/libs/cua/python/src/cua/_native.py
index f7d622e678..82f959c6d4 100644
--- a/libs/cua/python/src/cua/_native.py
+++ b/libs/cua/python/src/cua/_native.py
@@ -1047,7 +1047,7 @@ def _uniffi_check_api_checksums(lib):
raise InternalError("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
if lib.uniffi_cua_sdk_checksum_method_space_request_site_login() != 2223:
raise InternalError("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
- if lib.uniffi_cua_sdk_checksum_method_space_screenshot() != 9108:
+ if lib.uniffi_cua_sdk_checksum_method_space_screenshot() != 41142:
raise InternalError("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
if lib.uniffi_cua_sdk_checksum_method_space_send_file() != 29056:
raise InternalError("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
@@ -1071,6 +1071,8 @@ def _uniffi_check_api_checksums(lib):
raise InternalError("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
if lib.uniffi_cua_sdk_checksum_method_space_teleport_manifest() != 31596:
raise InternalError("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
+ if lib.uniffi_cua_sdk_checksum_method_space_thumbnail() != 10979:
+ raise InternalError("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
if lib.uniffi_cua_sdk_checksum_method_space_unshare() != 58172:
raise InternalError("UniFFI API checksum mismatch: try cleaning and rebuilding your project")
if lib.uniffi_cua_sdk_checksum_method_space_upload() != 30524:
@@ -3548,6 +3550,11 @@ _UniffiLib.uniffi_cua_sdk_fn_method_space_teleport_manifest.argtypes = (
_UniffiRustBuffer,
)
_UniffiLib.uniffi_cua_sdk_fn_method_space_teleport_manifest.restype = ctypes.c_uint64
+_UniffiLib.uniffi_cua_sdk_fn_method_space_thumbnail.argtypes = (
+ ctypes.c_uint64,
+ _UniffiRustBuffer,
+)
+_UniffiLib.uniffi_cua_sdk_fn_method_space_thumbnail.restype = ctypes.c_uint64
_UniffiLib.uniffi_cua_sdk_fn_method_space_unshare.argtypes = (
ctypes.c_uint64,
_UniffiRustBuffer,
@@ -5202,6 +5209,9 @@ _UniffiLib.uniffi_cua_sdk_checksum_method_space_teleport.restype = ctypes.c_uint
_UniffiLib.uniffi_cua_sdk_checksum_method_space_teleport_manifest.argtypes = (
)
_UniffiLib.uniffi_cua_sdk_checksum_method_space_teleport_manifest.restype = ctypes.c_uint16
+_UniffiLib.uniffi_cua_sdk_checksum_method_space_thumbnail.argtypes = (
+)
+_UniffiLib.uniffi_cua_sdk_checksum_method_space_thumbnail.restype = ctypes.c_uint16
_UniffiLib.uniffi_cua_sdk_checksum_method_space_unshare.argtypes = (
)
_UniffiLib.uniffi_cua_sdk_checksum_method_space_unshare.restype = ctypes.c_uint16
@@ -19786,6 +19796,64 @@ class _UniffiFfiConverterTypeSpaceStreamTicket(_UniffiConverterRustBuffer):
_UniffiFfiConverterUInt32.write(value.height, buf)
_UniffiFfiConverterBoolean.write(value.needs_headers, buf)
+@dataclass
+class SpaceThumbnail:
+ """
+ A Space's latest thumbnail, from the cache every client on this machine
+ shares ([`crate::native::spaces::Space::thumbnail`]).
+"""
+ def __init__(self, *, image:bytes, format:ImageFormat, width:int, height:int, captured_at_ms:int):
+ self.image = image
+ self.format = format
+ self.width = width
+ self.height = height
+ self.captured_at_ms = captured_at_ms
+
+
+
+
+ def __str__(self):
+ return "SpaceThumbnail(image={}, format={}, width={}, height={}, captured_at_ms={})".format(self.image, self.format, self.width, self.height, self.captured_at_ms)
+ def __eq__(self, other):
+ if self.image != other.image:
+ return False
+ if self.format != other.format:
+ return False
+ if self.width != other.width:
+ return False
+ if self.height != other.height:
+ return False
+ if self.captured_at_ms != other.captured_at_ms:
+ return False
+ return True
+
+class _UniffiFfiConverterTypeSpaceThumbnail(_UniffiConverterRustBuffer):
+ @staticmethod
+ def read(buf):
+ return SpaceThumbnail(
+ image=_UniffiFfiConverterBytes.read(buf),
+ format=_UniffiFfiConverterTypeImageFormat.read(buf),
+ width=_UniffiFfiConverterUInt32.read(buf),
+ height=_UniffiFfiConverterUInt32.read(buf),
+ captured_at_ms=_UniffiFfiConverterUInt64.read(buf),
+ )
+
+ @staticmethod
+ def check_lower(value):
+ _UniffiFfiConverterBytes.check_lower(value.image)
+ _UniffiFfiConverterTypeImageFormat.check_lower(value.format)
+ _UniffiFfiConverterUInt32.check_lower(value.width)
+ _UniffiFfiConverterUInt32.check_lower(value.height)
+ _UniffiFfiConverterUInt64.check_lower(value.captured_at_ms)
+
+ @staticmethod
+ def write(value, buf):
+ _UniffiFfiConverterBytes.write(value.image, buf)
+ _UniffiFfiConverterTypeImageFormat.write(value.format, buf)
+ _UniffiFfiConverterUInt32.write(value.width, buf)
+ _UniffiFfiConverterUInt32.write(value.height, buf)
+ _UniffiFfiConverterUInt64.write(value.captured_at_ms, buf)
+
@dataclass
class SpaceToolInfo:
"""
@@ -32134,10 +32202,10 @@ class SpaceProtocol(typing.Protocol):
raise NotImplementedError
async def screenshot(self, options: typing.Optional[ScreenshotOptions]) -> Screenshot:
"""
- Captures the Space's display (the app's tile thumbnails): PNG at
- full size on the primary display unless `options` say otherwise.
- Fails with `CapabilityMissing` (`spacesd`) when the image runs no
- cua-spacesd.
+ Captures the Space's display: PNG at full size on the primary
+ display unless `options` say otherwise (for a small preview,
+ [`Space::thumbnail`] reads the shared cache instead). Fails with
+ `CapabilityMissing` (`spacesd`) when the image runs no cua-spacesd.
"""
raise NotImplementedError
async def send_file(self, local_path: str,options: SpaceSendFileOptions) -> SpaceSendFileReport:
@@ -32217,6 +32285,17 @@ class SpaceProtocol(typing.Protocol):
async def teleport_manifest(self, app: str,scope: typing.Optional[str]) -> TeleportManifest:
"""
What teleporting `app` (`full` or `tabs`) would move from this host.
+"""
+ raise NotImplementedError
+ async def thumbnail(self, max_age_ms: typing.Optional[int]) -> SpaceThumbnail:
+ """
+ The Space's latest thumbnail (a small JPEG of its primary display)
+ from the cache every client on this machine shares: returned at
+ once when it is younger than `max_age_ms` (unset: any age), else
+ captured fresh through cua-spacesd and kept for the next caller.
+ When that capture fails, the older one comes back (`captured_at_ms`
+ says how old). Asking keeps the daemon refreshing running Spaces'
+ thumbnails in the background for a while (about every 90 s).
"""
raise NotImplementedError
async def unshare(self, who: typing.Optional[str]) -> SpaceShares:
@@ -32835,10 +32914,10 @@ class Space(SpaceProtocol):
)
async def screenshot(self, options: typing.Optional[ScreenshotOptions]) -> Screenshot:
"""
- Captures the Space's display (the app's tile thumbnails): PNG at
- full size on the primary display unless `options` say otherwise.
- Fails with `CapabilityMissing` (`spacesd`) when the image runs no
- cua-spacesd.
+ Captures the Space's display: PNG at full size on the primary
+ display unless `options` say otherwise (for a small preview,
+ [`Space::thumbnail`] reads the shared cache instead). Fails with
+ `CapabilityMissing` (`spacesd`) when the image runs no cua-spacesd.
"""
_UniffiFfiConverterOptionalTypeScreenshotOptions.check_lower(options)
@@ -33118,6 +33197,32 @@ class Space(SpaceProtocol):
_uniffi_lift_return,
_uniffi_error_converter,
)
+ async def thumbnail(self, max_age_ms: typing.Optional[int]) -> SpaceThumbnail:
+ """
+ The Space's latest thumbnail (a small JPEG of its primary display)
+ from the cache every client on this machine shares: returned at
+ once when it is younger than `max_age_ms` (unset: any age), else
+ captured fresh through cua-spacesd and kept for the next caller.
+ When that capture fails, the older one comes back (`captured_at_ms`
+ says how old). Asking keeps the daemon refreshing running Spaces'
+ thumbnails in the background for a while (about every 90 s).
+"""
+
+ _UniffiFfiConverterOptionalUInt64.check_lower(max_age_ms)
+ _uniffi_lowered_args = (
+ self._uniffi_clone_handle(),
+ _UniffiFfiConverterOptionalUInt64.lower(max_age_ms),
+ )
+ _uniffi_lift_return = _UniffiFfiConverterTypeSpaceThumbnail.lift
+ _uniffi_error_converter = _UniffiFfiConverterTypeCuaError
+ return await _uniffi_rust_call_async(
+ _UniffiLib.uniffi_cua_sdk_fn_method_space_thumbnail(*_uniffi_lowered_args),
+ _UniffiLib.ffi_cua_sdk_rust_future_poll_rust_buffer,
+ _UniffiLib.ffi_cua_sdk_rust_future_complete_rust_buffer,
+ _UniffiLib.ffi_cua_sdk_rust_future_free_rust_buffer,
+ _uniffi_lift_return,
+ _uniffi_error_converter,
+ )
async def unshare(self, who: typing.Optional[str]) -> SpaceShares:
"""
Stops sharing this Space with `who` at once, or with everyone when
@@ -37470,6 +37575,7 @@ __all__ = [
"SpaceStreamOptions",
"SpaceStreamStats",
"SpaceStreamTicket",
+ "SpaceThumbnail",
"SpaceToolInfo",
"SpaceToolResult",
"SpaceTransferReport",
diff --git a/libs/cua/scripts/generate-app-core-ffi.py b/libs/cua/scripts/generate-app-core-ffi.py
index 2f108e8426..50976f1ec2 100644
--- a/libs/cua/scripts/generate-app-core-ffi.py
+++ b/libs/cua/scripts/generate-app-core-ffi.py
@@ -24,6 +24,7 @@ TYPES = [
("spaces/roster.rs", "spaces::roster", ["NoticeKind", "Notice", "RosterState", "RosterAction"]),
("spaces/creating.rs", "spaces::creating", ["PendingCreate", "PendingDelete", "PendingPower", "CreatesState", "CreateAction"]),
("spaces/sidebar.rs", "spaces::sidebar", ["PowerButton", "SidebarRow", "SidebarSection", "SidebarView", "FactCopy", "FactWarning", "Fact", "DetailActionId", "DetailAction", "DeleteConfirm", "DetailCopy", "SpaceUsage", "SpaceDetail"]),
+ ("spaces/cover.rs", "spaces::cover", ["StreamPhase", "DesktopCoverInput", "DesktopCoverKind", "DesktopCover", "ThumbnailPolicy"]),
("spaces/stream.rs", "spaces::stream", ["StreamDisplay", "StreamSectionInput", "StreamRowKind", "StreamRowIcon", "StreamRowActionId", "StreamRowAction", "StreamRow", "StreamSection", "PipEvent", "PipCommand"]),
("notch/geometry.rs", "notch::geometry", ["WindowMode", "LogicalRect"]),
("teleport/drag.rs", "teleport::drag", ["DragOverlayPhase", "DragOverlayState", "DragOverlayEvent", "DragOverlayEffect", "DragOverlayTransition"]),
diff --git a/libs/cua/swift/Sources/CuaSDK/CuaSDK.swift b/libs/cua/swift/Sources/CuaSDK/CuaSDK.swift
index f86a22ff1a..9c879f7a44 100644
--- a/libs/cua/swift/Sources/CuaSDK/CuaSDK.swift
+++ b/libs/cua/swift/Sources/CuaSDK/CuaSDK.swift
@@ -8306,10 +8306,10 @@ public protocol SpaceProtocol: AnyObject, Sendable {
func requestSiteLogin(url: String, options: SiteLoginOptions?) async throws -> SiteLoginReport
/**
- * Captures the Space's display (the app's tile thumbnails): PNG at
- * full size on the primary display unless `options` say otherwise.
- * Fails with `CapabilityMissing` (`spacesd`) when the image runs no
- * cua-spacesd.
+ * Captures the Space's display: PNG at full size on the primary
+ * display unless `options` say otherwise (for a small preview,
+ * [`Space::thumbnail`] reads the shared cache instead). Fails with
+ * `CapabilityMissing` (`spacesd`) when the image runs no cua-spacesd.
*/
func screenshot(options: ScreenshotOptions?) async throws -> Screenshot
@@ -8392,6 +8392,17 @@ public protocol SpaceProtocol: AnyObject, Sendable {
*/
func teleportManifest(app: String, scope: String?) async throws -> TeleportManifest
+ /**
+ * The Space's latest thumbnail (a small JPEG of its primary display)
+ * from the cache every client on this machine shares: returned at
+ * once when it is younger than `max_age_ms` (unset: any age), else
+ * captured fresh through cua-spacesd and kept for the next caller.
+ * When that capture fails, the older one comes back (`captured_at_ms`
+ * says how old). Asking keeps the daemon refreshing running Spaces'
+ * thumbnails in the background for a while (about every 90 s).
+ */
+ func thumbnail(maxAgeMs: UInt64?) async throws -> SpaceThumbnail
+
/**
* Stops sharing this Space with `who` at once, or with everyone when
* `who` is `None`.
@@ -8972,10 +8983,10 @@ open func requestSiteLogin(url: String, options: SiteLoginOptions?)async throws
}
/**
- * Captures the Space's display (the app's tile thumbnails): PNG at
- * full size on the primary display unless `options` say otherwise.
- * Fails with `CapabilityMissing` (`spacesd`) when the image runs no
- * cua-spacesd.
+ * Captures the Space's display: PNG at full size on the primary
+ * display unless `options` say otherwise (for a small preview,
+ * [`Space::thumbnail`] reads the shared cache instead). Fails with
+ * `CapabilityMissing` (`spacesd`) when the image runs no cua-spacesd.
*/
open func screenshot(options: ScreenshotOptions?)async throws -> Screenshot {
return
@@ -9221,6 +9232,32 @@ open func teleportManifest(app: String, scope: String?)async throws -> Teleport
)
}
+ /**
+ * The Space's latest thumbnail (a small JPEG of its primary display)
+ * from the cache every client on this machine shares: returned at
+ * once when it is younger than `max_age_ms` (unset: any age), else
+ * captured fresh through cua-spacesd and kept for the next caller.
+ * When that capture fails, the older one comes back (`captured_at_ms`
+ * says how old). Asking keeps the daemon refreshing running Spaces'
+ * thumbnails in the background for a while (about every 90 s).
+ */
+open func thumbnail(maxAgeMs: UInt64?)async throws -> SpaceThumbnail {
+ return
+ try await uniffiRustCallAsync(
+ rustFutureFunc: {
+ uniffi_cua_sdk_fn_method_space_thumbnail(
+ self.uniffiCloneHandle(),
+ FfiConverterOptionUInt64.lower(maxAgeMs)
+ )
+ },
+ pollFunc: ffi_cua_sdk_rust_future_poll_rust_buffer,
+ completeFunc: ffi_cua_sdk_rust_future_complete_rust_buffer,
+ freeFunc: ffi_cua_sdk_rust_future_free_rust_buffer,
+ liftFunc: FfiConverterTypeSpaceThumbnail_lift,
+ errorHandler: FfiConverterTypeCuaError_lift
+ )
+}
+
/**
* Stops sharing this Space with `who` at once, or with everyone when
* `who` is `None`.
@@ -31196,6 +31233,106 @@ public func FfiConverterTypeSpaceStreamTicket_lower(_ value: SpaceStreamTicket)
}
+/**
+ * A Space's latest thumbnail, from the cache every client on this machine
+ * shares ([`crate::native::spaces::Space::thumbnail`]).
+ */
+public struct SpaceThumbnail: Equatable, Hashable {
+ /**
+ * Encoded image (a small JPEG of the primary display).
+ */
+ public var image: Data
+ /**
+ * Encoding.
+ */
+ public var format: ImageFormat
+ /**
+ * Pixel width.
+ */
+ public var width: UInt32
+ /**
+ * Pixel height.
+ */
+ public var height: UInt32
+ /**
+ * When it was captured, Unix milliseconds.
+ */
+ public var capturedAtMs: UInt64
+
+ // Default memberwise initializers are never public by default, so we
+ // declare one manually.
+ public init(
+ /**
+ * Encoded image (a small JPEG of the primary display).
+ */image: Data,
+ /**
+ * Encoding.
+ */format: ImageFormat,
+ /**
+ * Pixel width.
+ */width: UInt32,
+ /**
+ * Pixel height.
+ */height: UInt32,
+ /**
+ * When it was captured, Unix milliseconds.
+ */capturedAtMs: UInt64) {
+ self.image = image
+ self.format = format
+ self.width = width
+ self.height = height
+ self.capturedAtMs = capturedAtMs
+ }
+
+
+
+
+}
+
+#if compiler(>=6)
+extension SpaceThumbnail: Sendable {}
+#endif
+
+#if swift(>=5.8)
+@_documentation(visibility: private)
+#endif
+public struct FfiConverterTypeSpaceThumbnail: FfiConverterRustBuffer {
+ public static func read(from buf: inout (data: Data, offset: Data.Index)) throws -> SpaceThumbnail {
+ return
+ try SpaceThumbnail(
+ image: FfiConverterData.read(from: &buf),
+ format: FfiConverterTypeImageFormat.read(from: &buf),
+ width: FfiConverterUInt32.read(from: &buf),
+ height: FfiConverterUInt32.read(from: &buf),
+ capturedAtMs: FfiConverterUInt64.read(from: &buf)
+ )
+ }
+
+ public static func write(_ value: SpaceThumbnail, into buf: inout [UInt8]) {
+ FfiConverterData.write(value.image, into: &buf)
+ FfiConverterTypeImageFormat.write(value.format, into: &buf)
+ FfiConverterUInt32.write(value.width, into: &buf)
+ FfiConverterUInt32.write(value.height, into: &buf)
+ FfiConverterUInt64.write(value.capturedAtMs, into: &buf)
+ }
+}
+
+
+#if swift(>=5.8)
+@_documentation(visibility: private)
+#endif
+public func FfiConverterTypeSpaceThumbnail_lift(_ buf: RustBuffer) throws -> SpaceThumbnail {
+ return try FfiConverterTypeSpaceThumbnail.lift(buf)
+}
+
+#if swift(>=5.8)
+@_documentation(visibility: private)
+#endif
+public func FfiConverterTypeSpaceThumbnail_lower(_ value: SpaceThumbnail) -> RustBuffer {
+ return FfiConverterTypeSpaceThumbnail.lower(value)
+}
+
+
/**
* A tool of a Space's MCP service.
*/
@@ -40437,7 +40574,7 @@ private let initializationResult: InitializationResult = {
if (uniffi_cua_sdk_checksum_method_space_request_site_login() != 2223) {
return InitializationResult.apiChecksumMismatch
}
- if (uniffi_cua_sdk_checksum_method_space_screenshot() != 9108) {
+ if (uniffi_cua_sdk_checksum_method_space_screenshot() != 41142) {
return InitializationResult.apiChecksumMismatch
}
if (uniffi_cua_sdk_checksum_method_space_send_file() != 29056) {
@@ -40473,6 +40610,9 @@ private let initializationResult: InitializationResult = {
if (uniffi_cua_sdk_checksum_method_space_teleport_manifest() != 31596) {
return InitializationResult.apiChecksumMismatch
}
+ if (uniffi_cua_sdk_checksum_method_space_thumbnail() != 10979) {
+ return InitializationResult.apiChecksumMismatch
+ }
if (uniffi_cua_sdk_checksum_method_space_unshare() != 58172) {
return InitializationResult.apiChecksumMismatch
}
diff --git a/libs/cua/swift/Sources/cua_sdkFFI/include/cua_sdkFFI.h b/libs/cua/swift/Sources/cua_sdkFFI/include/cua_sdkFFI.h
index 866de0b986..80b15ae8f4 100644
--- a/libs/cua/swift/Sources/cua_sdkFFI/include/cua_sdkFFI.h
+++ b/libs/cua/swift/Sources/cua_sdkFFI/include/cua_sdkFFI.h
@@ -1781,6 +1781,11 @@ uint64_t uniffi_cua_sdk_fn_method_space_teleport(uint64_t ptr, RustBuffer app, R
uint64_t uniffi_cua_sdk_fn_method_space_teleport_manifest(uint64_t ptr, RustBuffer app, RustBuffer scope
);
#endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_CUA_SDK_FN_METHOD_SPACE_THUMBNAIL
+#define UNIFFI_FFIDEF_UNIFFI_CUA_SDK_FN_METHOD_SPACE_THUMBNAIL
+uint64_t uniffi_cua_sdk_fn_method_space_thumbnail(uint64_t ptr, RustBuffer max_age_ms
+);
+#endif
#ifndef UNIFFI_FFIDEF_UNIFFI_CUA_SDK_FN_METHOD_SPACE_UNSHARE
#define UNIFFI_FFIDEF_UNIFFI_CUA_SDK_FN_METHOD_SPACE_UNSHARE
uint64_t uniffi_cua_sdk_fn_method_space_unshare(uint64_t ptr, RustBuffer who
@@ -4848,6 +4853,12 @@ uint16_t uniffi_cua_sdk_checksum_method_space_teleport(void
#define UNIFFI_FFIDEF_UNIFFI_CUA_SDK_CHECKSUM_METHOD_SPACE_TELEPORT_MANIFEST
uint16_t uniffi_cua_sdk_checksum_method_space_teleport_manifest(void
+);
+#endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_CUA_SDK_CHECKSUM_METHOD_SPACE_THUMBNAIL
+#define UNIFFI_FFIDEF_UNIFFI_CUA_SDK_CHECKSUM_METHOD_SPACE_THUMBNAIL
+uint16_t uniffi_cua_sdk_checksum_method_space_thumbnail(void
+
);
#endif
#ifndef UNIFFI_FFIDEF_UNIFFI_CUA_SDK_CHECKSUM_METHOD_SPACE_UNSHARE
diff --git a/libs/cua/typescript/src/native/cua_sdk-ffi.ts b/libs/cua/typescript/src/native/cua_sdk-ffi.ts
index 1c33acde7c..d6c4aa2529 100644
--- a/libs/cua/typescript/src/native/cua_sdk-ffi.ts
+++ b/libs/cua/typescript/src/native/cua_sdk-ffi.ts
@@ -2073,6 +2073,11 @@ const DEFINITIONS = {
ret: FfiType.Handle,
hasRustCallStatus: false,
},
+ "uniffi_cua_sdk_fn_method_space_thumbnail": {
+ args: [FfiType.Handle, FfiType.RustBuffer],
+ ret: FfiType.Handle,
+ hasRustCallStatus: false,
+ },
"uniffi_cua_sdk_fn_method_space_unshare": {
args: [FfiType.Handle, FfiType.RustBuffer],
ret: FfiType.Handle,
@@ -4268,6 +4273,11 @@ const DEFINITIONS = {
ret: FfiType.UInt16,
hasRustCallStatus: false,
},
+ "uniffi_cua_sdk_checksum_method_space_thumbnail": {
+ args: [],
+ ret: FfiType.UInt16,
+ hasRustCallStatus: false,
+ },
"uniffi_cua_sdk_checksum_method_space_unshare": {
args: [],
ret: FfiType.UInt16,
@@ -5501,6 +5511,7 @@ interface NativeModuleInterface {
uniffi_cua_sdk_fn_method_space_supports(uniffiSelf: bigint, feature: Uint8Array, uniffi_out_err: UniffiRustCallStatus): number;
uniffi_cua_sdk_fn_method_space_teleport(uniffiSelf: bigint, app: Uint8Array, scope: Uint8Array, approver: bigint, requestId: Uint8Array): bigint;
uniffi_cua_sdk_fn_method_space_teleport_manifest(uniffiSelf: bigint, app: Uint8Array, scope: Uint8Array): bigint;
+ uniffi_cua_sdk_fn_method_space_thumbnail(uniffiSelf: bigint, maxAgeMs: Uint8Array): bigint;
uniffi_cua_sdk_fn_method_space_unshare(uniffiSelf: bigint, who: Uint8Array): bigint;
uniffi_cua_sdk_fn_method_space_upload(uniffiSelf: bigint, localPath: Uint8Array, dest: Uint8Array): bigint;
uniffi_cua_sdk_fn_method_space_usage(uniffiSelf: bigint): bigint;
@@ -5940,6 +5951,7 @@ interface NativeModuleInterface {
uniffi_cua_sdk_checksum_method_space_supports(): number;
uniffi_cua_sdk_checksum_method_space_teleport(): number;
uniffi_cua_sdk_checksum_method_space_teleport_manifest(): number;
+ uniffi_cua_sdk_checksum_method_space_thumbnail(): number;
uniffi_cua_sdk_checksum_method_space_unshare(): number;
uniffi_cua_sdk_checksum_method_space_upload(): number;
uniffi_cua_sdk_checksum_method_space_usage(): number;
diff --git a/libs/cua/typescript/src/native/cua_sdk.ts b/libs/cua/typescript/src/native/cua_sdk.ts
index eff337cba8..57723924db 100644
--- a/libs/cua/typescript/src/native/cua_sdk.ts
+++ b/libs/cua/typescript/src/native/cua_sdk.ts
@@ -15372,6 +15372,80 @@ const FfiConverterTypeSpaceStreamTicket = (() => {
return new FFIConverter();
})();
+/**
+ * A Space's latest thumbnail, from the cache every client on this machine
+ * shares ([`crate::native::spaces::Space::thumbnail`]).
+ */
+export type SpaceThumbnail = {
+ /**
+ * Encoded image (a small JPEG of the primary display).
+ */
+ image: ArrayBuffer,
+ /**
+ * Encoding.
+ */
+ format: ImageFormat,
+ /**
+ * Pixel width.
+ */
+ width: number,
+ /**
+ * Pixel height.
+ */
+ height: number,
+ /**
+ * When it was captured, Unix milliseconds.
+ */
+ capturedAtMs: bigint
+}
+
+/**
+ * Generated factory for {@link SpaceThumbnail} record objects.
+ */
+export const SpaceThumbnail = (() => {
+ const defaults = () => ({
+ });
+ const create = (() => {
+ return uniffiCreateRecord<SpaceThumbnail, ReturnType<typeof defaults>>(defaults);
+ })();
+ return Object.freeze({
+ create,
+ new: create,
+ defaults: () => Object.freeze(defaults()) as Partial<SpaceThumbnail>,
+ });
+})();
+
+const FfiConverterTypeSpaceThumbnail = (() => {
+ type TypeName = SpaceThumbnail;
+ class FFIConverter extends AbstractFfiConverterByteArray<TypeName> {
+ read(from: RustBuffer): TypeName {
+ return {
+ image: FfiConverterArrayBuffer.read(from),
+ format: FfiConverterTypeImageFormat.read(from),
+ width: FfiConverterUInt32.read(from),
+ height: FfiConverterUInt32.read(from),
+ capturedAtMs: FfiConverterUInt64.read(from)
+ };
+ }
+ write(value: TypeName, into: RustBuffer): void {
+ FfiConverterArrayBuffer.write(value.image, into);
+ FfiConverterTypeImageFormat.write(value.format, into);
+ FfiConverterUInt32.write(value.width, into);
+ FfiConverterUInt32.write(value.height, into);
+ FfiConverterUInt64.write(value.capturedAtMs, into);
+ }
+ allocationSize(value: TypeName): number {
+ return FfiConverterArrayBuffer.allocationSize(value.image) +
+ FfiConverterTypeImageFormat.allocationSize(value.format) +
+ FfiConverterUInt32.allocationSize(value.width) +
+ FfiConverterUInt32.allocationSize(value.height) +
+ FfiConverterUInt64.allocationSize(value.capturedAtMs);
+
+ }
+ };
+ return new FFIConverter();
+})();
+
/**
* A tool of a Space's MCP service.
*/
@@ -30491,10 +30565,10 @@ export interface SpaceLike {
*/
requestSiteLogin(url: string, options: SiteLoginOptions | undefined, asyncOpts_?: { signal: AbortSignal }) /*throws*/: Promise<SiteLoginReport>;
/**
- * Captures the Space's display (the app's tile thumbnails): PNG at
- * full size on the primary display unless `options` say otherwise.
- * Fails with `CapabilityMissing` (`spacesd`) when the image runs no
- * cua-spacesd.
+ * Captures the Space's display: PNG at full size on the primary
+ * display unless `options` say otherwise (for a small preview,
+ * [`Space::thumbnail`] reads the shared cache instead). Fails with
+ * `CapabilityMissing` (`spacesd`) when the image runs no cua-spacesd.
*/
screenshot(options: ScreenshotOptions | undefined, asyncOpts_?: { signal: AbortSignal }) /*throws*/: Promise<Screenshot>;
/**
@@ -30565,6 +30639,16 @@ export interface SpaceLike {
* What teleporting `app` (`full` or `tabs`) would move from this host.
*/
teleportManifest(app: string, scope: string | undefined, asyncOpts_?: { signal: AbortSignal }) /*throws*/: Promise<TeleportManifest>;
+/**
+ * The Space's latest thumbnail (a small JPEG of its primary display)
+ * from the cache every client on this machine shares: returned at
+ * once when it is younger than `max_age_ms` (unset: any age), else
+ * captured fresh through cua-spacesd and kept for the next caller.
+ * When that capture fails, the older one comes back (`captured_at_ms`
+ * says how old). Asking keeps the daemon refreshing running Spaces'
+ * thumbnails in the background for a while (about every 90 s).
+ */
+ thumbnail(maxAgeMs: bigint | undefined, asyncOpts_?: { signal: AbortSignal }) /*throws*/: Promise<SpaceThumbnail>;
/**
* Stops sharing this Space with `who` at once, or with everyone when
* `who` is `None`.
@@ -31444,10 +31528,10 @@ private constructor(pointer: UniffiHandle) {
}
/**
- * Captures the Space's display (the app's tile thumbnails): PNG at
- * full size on the primary display unless `options` say otherwise.
- * Fails with `CapabilityMissing` (`spacesd`) when the image runs no
- * cua-spacesd.
+ * Captures the Space's display: PNG at full size on the primary
+ * display unless `options` say otherwise (for a small preview,
+ * [`Space::thumbnail`] reads the shared cache instead). Fails with
+ * `CapabilityMissing` (`spacesd`) when the image runs no cua-spacesd.
*/
async screenshot(options: ScreenshotOptions | undefined, asyncOpts_?: { signal: AbortSignal }): Promise<Screenshot> /*throws*/ {
const __stack = uniffiIsDebug ? new Error().stack : undefined;
@@ -31850,6 +31934,47 @@ private constructor(pointer: UniffiHandle) {
}
}
+/**
+ * The Space's latest thumbnail (a small JPEG of its primary display)
+ * from the cache every client on this machine shares: returned at
+ * once when it is younger than `max_age_ms` (unset: any age), else
+ * captured fresh through cua-spacesd and kept for the next caller.
+ * When that capture fails, the older one comes back (`captured_at_ms`
+ * says how old). Asking keeps the daemon refreshing running Spaces'
+ * thumbnails in the background for a while (about every 90 s).
+ */
+ async thumbnail(maxAgeMs: bigint | undefined, asyncOpts_?: { signal: AbortSignal }): Promise<SpaceThumbnail> /*throws*/ {
+ const __stack = uniffiIsDebug ? new Error().stack : undefined;
+ try {
+ return await uniffiRustCallAsync(
+ /*rustCaller:*/ uniffiCaller,
+ /*rustFutureFunc:*/ () => {
+ return nativeModule().uniffi_cua_sdk_fn_method_space_thumbnail(
+ uniffiTypeSpaceObjectFactory.clonePointer(this),FfiConverterOptionalUInt64.lower(maxAgeMs, nativeModule().rustbuffer_alloc)
+ );
+ },
+ /*pollFunc:*/ nativeModule().ffi_cua_sdk_rust_future_poll_rust_buffer,
+ /*cancelFunc:*/ nativeModule().ffi_cua_sdk_rust_future_cancel_rust_buffer,
+ /*completeFunc:*/ nativeModule().ffi_cua_sdk_rust_future_complete_rust_buffer,
+ /*freeFunc:*/ nativeModule().ffi_cua_sdk_rust_future_free_rust_buffer,
+ // Async returns always go through the JS-side converter: the
+ // FFI symbol returns the future handle (u64), and the user-level
+ // RustBuffer comes back via the shared `rust_future_complete_*`
+ // export. The bytes the runtime hands back must be deserialized
+ // here using the per-callable return-type converter.
+ /*liftFunc:*/ FfiConverterTypeSpaceThumbnail.lift.bind(FfiConverterTypeSpaceThumbnail),
+ /*liftString:*/ FfiConverterString.lift.bind(FfiConverterString),
+ /*asyncOpts:*/ asyncOpts_,
+ /*errorHandler:*/ FfiConverterTypeCuaError.lift.bind(FfiConverterTypeCuaError)
+ );
+ } catch (__error: any) {
+ if (uniffiIsDebug && __error instanceof Error) {
+ __error.stack = __stack;
+ }
+ throw __error;
+ }
+ }
+
/**
* Stops sharing this Space with `who` at once, or with everyone when
* `who` is `None`.
@@ -37344,7 +37469,7 @@ function uniffiEnsureInitialized() {
if (nativeModule().uniffi_cua_sdk_checksum_method_space_request_site_login() !== 2223) {
throw new UniffiInternalError.ApiChecksumMismatch("uniffi_cua_sdk_checksum_method_space_request_site_login");
}
- if (nativeModule().uniffi_cua_sdk_checksum_method_space_screenshot() !== 9108) {
+ if (nativeModule().uniffi_cua_sdk_checksum_method_space_screenshot() !== 41142) {
throw new UniffiInternalError.ApiChecksumMismatch("uniffi_cua_sdk_checksum_method_space_screenshot");
}
if (nativeModule().uniffi_cua_sdk_checksum_method_space_send_file() !== 29056) {
@@ -37380,6 +37505,9 @@ function uniffiEnsureInitialized() {
if (nativeModule().uniffi_cua_sdk_checksum_method_space_teleport_manifest() !== 31596) {
throw new UniffiInternalError.ApiChecksumMismatch("uniffi_cua_sdk_checksum_method_space_teleport_manifest");
}
+ if (nativeModule().uniffi_cua_sdk_checksum_method_space_thumbnail() !== 10979) {
+ throw new UniffiInternalError.ApiChecksumMismatch("uniffi_cua_sdk_checksum_method_space_thumbnail");
+ }
if (nativeModule().uniffi_cua_sdk_checksum_method_space_unshare() !== 58172) {
throw new UniffiInternalError.ApiChecksumMismatch("uniffi_cua_sdk_checksum_method_space_unshare");
}
@@ -38022,6 +38150,7 @@ export default Object.freeze({
FfiConverterTypeSpaceStreamSession,
FfiConverterTypeSpaceStreamStats,
FfiConverterTypeSpaceStreamTicket,
+ FfiConverterTypeSpaceThumbnail,
FfiConverterTypeSpaceToolInfo,
FfiConverterTypeSpaceToolResult,
FfiConverterTypeSpaceTransferReport,
diff --git a/libs/spaces-app-swift/Sources/CuaSpacesFFI/CuaSpacesFFI.swift b/libs/spaces-app-swift/Sources/CuaSpacesFFI/CuaSpacesFFI.swift
index b77495330c..8536308c6a 100644
--- a/libs/spaces-app-swift/Sources/CuaSpacesFFI/CuaSpacesFFI.swift
+++ b/libs/spaces-app-swift/Sources/CuaSpacesFFI/CuaSpacesFFI.swift
@@ -8277,6 +8277,210 @@ public func FfiConverterTypeAppDeleteConfirm_lower(_ value: AppDeleteConfirm) ->
}
+public struct AppDesktopCover: Equatable, Hashable {
+ /**
+ * How it draws.
+ */
+ public var kind: AppDesktopCoverKind
+ /**
+ * The line, centered.
+ */
+ public var text: String?
+ /**
+ * A button under (or instead of) the line.
+ */
+ public var button: String?
+ /**
+ * Its tooltip.
+ */
+ public var buttonHelp: String?
+ /**
+ * The shell opens a stream session now (none is open, and one is
+ * wanted).
+ */
+ public var openStream: Bool
+ /**
+ * The shell starts the open session again (Try again was pressed).
+ */
+ public var retry: Bool
+
+ // Default memberwise initializers are never public by default, so we
+ // declare one manually.
+ public init(
+ /**
+ * How it draws.
+ */kind: AppDesktopCoverKind,
+ /**
+ * The line, centered.
+ */text: String?,
+ /**
+ * A button under (or instead of) the line.
+ */button: String?,
+ /**
+ * Its tooltip.
+ */buttonHelp: String?,
+ /**
+ * The shell opens a stream session now (none is open, and one is
+ * wanted).
+ */openStream: Bool,
+ /**
+ * The shell starts the open session again (Try again was pressed).
+ */retry: Bool) {
+ self.kind = kind
+ self.text = text
+ self.button = button
+ self.buttonHelp = buttonHelp
+ self.openStream = openStream
+ self.retry = retry
+ }
+
+
+
+
+}
+
+#if compiler(>=6)
+extension AppDesktopCover: Sendable {}
+#endif
+
+#if swift(>=5.8)
+@_documentation(visibility: private)
+#endif
+public struct FfiConverterTypeAppDesktopCover: FfiConverterRustBuffer {
+ public static func read(from buf: inout (data: Data, offset: Data.Index)) throws -> AppDesktopCover {
+ return
+ try AppDesktopCover(
+ kind: FfiConverterTypeAppDesktopCoverKind.read(from: &buf),
+ text: FfiConverterOptionString.read(from: &buf),
+ button: FfiConverterOptionString.read(from: &buf),
+ buttonHelp: FfiConverterOptionString.read(from: &buf),
+ openStream: FfiConverterBool.read(from: &buf),
+ retry: FfiConverterBool.read(from: &buf)
+ )
+ }
+
+ public static func write(_ value: AppDesktopCover, into buf: inout [UInt8]) {
+ FfiConverterTypeAppDesktopCoverKind.write(value.kind, into: &buf)
+ FfiConverterOptionString.write(value.text, into: &buf)
+ FfiConverterOptionString.write(value.button, into: &buf)
+ FfiConverterOptionString.write(value.buttonHelp, into: &buf)
+ FfiConverterBool.write(value.openStream, into: &buf)
+ FfiConverterBool.write(value.retry, into: &buf)
+ }
+}
+
+
+#if swift(>=5.8)
+@_documentation(visibility: private)
+#endif
+public func FfiConverterTypeAppDesktopCover_lift(_ buf: RustBuffer) throws -> AppDesktopCover {
+ return try FfiConverterTypeAppDesktopCover.lift(buf)
+}
+
+#if swift(>=5.8)
+@_documentation(visibility: private)
+#endif
+public func FfiConverterTypeAppDesktopCover_lower(_ value: AppDesktopCover) -> RustBuffer {
+ return FfiConverterTypeAppDesktopCover.lower(value)
+}
+
+
+public struct AppDesktopCoverInput: Equatable, Hashable {
+ /**
+ * The detail's `can_stream`.
+ */
+ public var canStream: Bool
+ /**
+ * The detail's `preview_text` (why it cannot stream).
+ */
+ public var previewText: String
+ /**
+ * Settings: "Connect to the desktop automatically".
+ */
+ public var autoConnect: Bool
+ /**
+ * Connect (or Try again) was pressed for this Space.
+ */
+ public var connectRequested: Bool
+ /**
+ * The shell's stream session.
+ */
+ public var stream: AppStreamPhase
+
+ // Default memberwise initializers are never public by default, so we
+ // declare one manually.
+ public init(
+ /**
+ * The detail's `can_stream`.
+ */canStream: Bool,
+ /**
+ * The detail's `preview_text` (why it cannot stream).
+ */previewText: String,
+ /**
+ * Settings: "Connect to the desktop automatically".
+ */autoConnect: Bool,
+ /**
+ * Connect (or Try again) was pressed for this Space.
+ */connectRequested: Bool,
+ /**
+ * The shell's stream session.
+ */stream: AppStreamPhase) {
+ self.canStream = canStream
+ self.previewText = previewText
+ self.autoConnect = autoConnect
+ self.connectRequested = connectRequested
+ self.stream = stream
+ }
+
+
+
+
+}
+
+#if compiler(>=6)
+extension AppDesktopCoverInput: Sendable {}
+#endif
+
+#if swift(>=5.8)
+@_documentation(visibility: private)
+#endif
+public struct FfiConverterTypeAppDesktopCoverInput: FfiConverterRustBuffer {
+ public static func read(from buf: inout (data: Data, offset: Data.Index)) throws -> AppDesktopCoverInput {
+ return
+ try AppDesktopCoverInput(
+ canStream: FfiConverterBool.read(from: &buf),
+ previewText: FfiConverterString.read(from: &buf),
+ autoConnect: FfiConverterBool.read(from: &buf),
+ connectRequested: FfiConverterBool.read(from: &buf),
+ stream: FfiConverterTypeAppStreamPhase.read(from: &buf)
+ )
+ }
+
+ public static func write(_ value: AppDesktopCoverInput, into buf: inout [UInt8]) {
+ FfiConverterBool.write(value.canStream, into: &buf)
+ FfiConverterString.write(value.previewText, into: &buf)
+ FfiConverterBool.write(value.autoConnect, into: &buf)
+ FfiConverterBool.write(value.connectRequested, into: &buf)
+ FfiConverterTypeAppStreamPhase.write(value.stream, into: &buf)
+ }
+}
+
+
+#if swift(>=5.8)
+@_documentation(visibility: private)
+#endif
+public func FfiConverterTypeAppDesktopCoverInput_lift(_ buf: RustBuffer) throws -> AppDesktopCoverInput {
+ return try FfiConverterTypeAppDesktopCoverInput.lift(buf)
+}
+
+#if swift(>=5.8)
+@_documentation(visibility: private)
+#endif
+public func FfiConverterTypeAppDesktopCoverInput_lower(_ value: AppDesktopCoverInput) -> RustBuffer {
+ return FfiConverterTypeAppDesktopCoverInput.lower(value)
+}
+
+
public struct AppDetailAction: Equatable, Hashable {
/**
* What it does.
@@ -24234,6 +24438,12 @@ public struct AppSettings: Equatable, Hashable {
* ([`crate::keyvault::view::prune_dismissed`] forgets the gone ones).
*/
public var dismissedAccess: [String]
+ /**
+ * Settings, General: a running Space's desktop streams as soon as it
+ * is opened (on by default); off, it waits for Connect
+ * ([`crate::spaces::cover`]).
+ */
+ public var autoConnect: Bool
// Default memberwise initializers are never public by default, so we
// declare one manually.
@@ -24276,7 +24486,12 @@ public struct AppSettings: Equatable, Hashable {
* Keyvault copies (import ids) the user dismissed from the notch: it no
* longer shows them, nothing is revoked or wiped
* ([`crate::keyvault::view::prune_dismissed`] forgets the gone ones).
- */dismissedAccess: [String]) {
+ */dismissedAccess: [String],
+ /**
+ * Settings, General: a running Space's desktop streams as soon as it
+ * is opened (on by default); off, it waits for Connect
+ * ([`crate::spaces::cover`]).
+ */autoConnect: Bool) {
self.hotkey = hotkey
self.menuBar = menuBar
self.theme = theme
@@ -24288,6 +24503,7 @@ public struct AppSettings: Equatable, Hashable {
self.launchAtLogin = launchAtLogin
self.experiments = experiments
self.dismissedAccess = dismissedAccess
+ self.autoConnect = autoConnect
}
@@ -24316,7 +24532,8 @@ public struct FfiConverterTypeAppSettings: FfiConverterRustBuffer {
updateChannel: FfiConverterTypeAppUpdateChannel.read(from: &buf),
launchAtLogin: FfiConverterOptionBool.read(from: &buf),
experiments: FfiConverterTypeAppExperiments.read(from: &buf),
- dismissedAccess: FfiConverterSequenceString.read(from: &buf)
+ dismissedAccess: FfiConverterSequenceString.read(from: &buf),
+ autoConnect: FfiConverterBool.read(from: &buf)
)
}
@@ -24332,6 +24549,7 @@ public struct FfiConverterTypeAppSettings: FfiConverterRustBuffer {
FfiConverterOptionBool.write(value.launchAtLogin, into: &buf)
FfiConverterTypeAppExperiments.write(value.experiments, into: &buf)
FfiConverterSequenceString.write(value.dismissedAccess, into: &buf)
+ FfiConverterBool.write(value.autoConnect, into: &buf)
}
}
@@ -24414,6 +24632,11 @@ public struct AppSettingsInput: Equatable, Hashable {
* Keyvault section).
*/
public var keyvaultAutoWipe: Bool?
+ /**
+ * "Connect to the desktop automatically" (none: no row; a shell
+ * without the preview cover leaves it out).
+ */
+ public var autoConnect: Bool?
// Default memberwise initializers are never public by default, so we
// declare one manually.
@@ -24464,7 +24687,11 @@ public struct AppSettingsInput: Equatable, Hashable {
/**
* The Keyvault's auto-wipe, once the broker told it (none: no
* Keyvault section).
- */keyvaultAutoWipe: Bool?) {
+ */keyvaultAutoWipe: Bool?,
+ /**
+ * "Connect to the desktop automatically" (none: no row; a shell
+ * without the preview cover leaves it out).
+ */autoConnect: Bool?) {
self.identity = identity
self.apiKeyClient = apiKeyClient
self.signIn = signIn
@@ -24480,6 +24707,7 @@ public struct AppSettingsInput: Equatable, Hashable {
self.loginItem = loginItem
self.experiments = experiments
self.keyvaultAutoWipe = keyvaultAutoWipe
+ self.autoConnect = autoConnect
}
@@ -24512,7 +24740,8 @@ public struct FfiConverterTypeAppSettingsInput: FfiConverterRustBuffer {
billing: FfiConverterOptionTypeAppBillingStatus.read(from: &buf),
loginItem: FfiConverterOptionTypeAppLoginItemInput.read(from: &buf),
experiments: FfiConverterTypeAppExperiments.read(from: &buf),
- keyvaultAutoWipe: FfiConverterOptionBool.read(from: &buf)
+ keyvaultAutoWipe: FfiConverterOptionBool.read(from: &buf),
+ autoConnect: FfiConverterOptionBool.read(from: &buf)
)
}
@@ -24532,6 +24761,7 @@ public struct FfiConverterTypeAppSettingsInput: FfiConverterRustBuffer {
FfiConverterOptionTypeAppLoginItemInput.write(value.loginItem, into: &buf)
FfiConverterTypeAppExperiments.write(value.experiments, into: &buf)
FfiConverterOptionBool.write(value.keyvaultAutoWipe, into: &buf)
+ FfiConverterOptionBool.write(value.autoConnect, into: &buf)
}
}
@@ -29129,6 +29359,94 @@ public func FfiConverterTypeAppThisDevice_lower(_ value: AppThisDevice) -> RustB
}
+public struct AppThumbnailPolicy: Equatable, Hashable {
+ /**
+ * While the notch is open: every running Space, this often.
+ */
+ public var openIntervalMs: UInt64
+ /**
+ * Otherwise (the app visible, not in Low Power Mode): a running Space
+ * whose thumbnail is older than this gets a new one.
+ */
+ public var backgroundIntervalMs: UInt64
+ /**
+ * The long edge of a captured thumbnail, in pixels.
+ */
+ public var maxDimension: UInt32
+ /**
+ * A thumbnail kept on disk longer than this is dropped at launch.
+ */
+ public var keepMs: UInt64
+
+ // Default memberwise initializers are never public by default, so we
+ // declare one manually.
+ public init(
+ /**
+ * While the notch is open: every running Space, this often.
+ */openIntervalMs: UInt64,
+ /**
+ * Otherwise (the app visible, not in Low Power Mode): a running Space
+ * whose thumbnail is older than this gets a new one.
+ */backgroundIntervalMs: UInt64,
+ /**
+ * The long edge of a captured thumbnail, in pixels.
+ */maxDimension: UInt32,
+ /**
+ * A thumbnail kept on disk longer than this is dropped at launch.
+ */keepMs: UInt64) {
+ self.openIntervalMs = openIntervalMs
+ self.backgroundIntervalMs = backgroundIntervalMs
+ self.maxDimension = maxDimension
+ self.keepMs = keepMs
+ }
+
+
+
+
+}
+
+#if compiler(>=6)
+extension AppThumbnailPolicy: Sendable {}
+#endif
+
+#if swift(>=5.8)
+@_documentation(visibility: private)
+#endif
+public struct FfiConverterTypeAppThumbnailPolicy: FfiConverterRustBuffer {
+ public static func read(from buf: inout (data: Data, offset: Data.Index)) throws -> AppThumbnailPolicy {
+ return
+ try AppThumbnailPolicy(
+ openIntervalMs: FfiConverterUInt64.read(from: &buf),
+ backgroundIntervalMs: FfiConverterUInt64.read(from: &buf),
+ maxDimension: FfiConverterUInt32.read(from: &buf),
+ keepMs: FfiConverterUInt64.read(from: &buf)
+ )
+ }
+
+ public static func write(_ value: AppThumbnailPolicy, into buf: inout [UInt8]) {
+ FfiConverterUInt64.write(value.openIntervalMs, into: &buf)
+ FfiConverterUInt64.write(value.backgroundIntervalMs, into: &buf)
+ FfiConverterUInt32.write(value.maxDimension, into: &buf)
+ FfiConverterUInt64.write(value.keepMs, into: &buf)
+ }
+}
+
+
+#if swift(>=5.8)
+@_documentation(visibility: private)
+#endif
+public func FfiConverterTypeAppThumbnailPolicy_lift(_ buf: RustBuffer) throws -> AppThumbnailPolicy {
+ return try FfiConverterTypeAppThumbnailPolicy.lift(buf)
+}
+
+#if swift(>=5.8)
+@_documentation(visibility: private)
+#endif
+public func FfiConverterTypeAppThumbnailPolicy_lower(_ value: AppThumbnailPolicy) -> RustBuffer {
+ return FfiConverterTypeAppThumbnailPolicy.lower(value)
+}
+
+
public struct AppTile: Equatable, Hashable {
/**
* Stable id (`linux`, `cloud`, `vm`, ...).
@@ -38818,6 +39136,100 @@ public func FfiConverterTypeAppCreateAction_lower(_ value: AppCreateAction) -> R
}
+// Note that we don't yet support `indirect` for enums.
+// See https://github.com/mozilla/uniffi-rs/issues/396 for further discussion.
+
+public enum AppDesktopCoverKind: Equatable, Hashable {
+
+ /**
+ * No cover: the live desktop (or the stream view's own badge).
+ */
+ case stream
+ /**
+ * The preview with "Connecting…".
+ */
+ case connecting
+ /**
+ * The preview with a Connect button.
+ */
+ case connect
+ /**
+ * The preview with a line (and maybe a button): the Space cannot
+ * stream, or the stream failed.
+ */
+ case status
+
+
+
+
+
+}
+
+#if compiler(>=6)
+extension AppDesktopCoverKind: Sendable {}
+#endif
+
+#if swift(>=5.8)
+@_documentation(visibility: private)
+#endif
+public struct FfiConverterTypeAppDesktopCoverKind: FfiConverterRustBuffer {
+ typealias SwiftType = AppDesktopCoverKind
+
+ public static func read(from buf: inout (data: Data, offset: Data.Index)) throws -> AppDesktopCoverKind {
+ let variant: Int32 = try readInt(&buf)
+ switch variant {
+
+ case 1: return .stream
+
+ case 2: return .connecting
+
+ case 3: return .connect
+
+ case 4: return .status
+
+ default: throw UniffiInternalError.unexpectedEnumCase
+ }
+ }
+
+ public static func write(_ value: AppDesktopCoverKind, into buf: inout [UInt8]) {
+ switch value {
+
+
+ case .stream:
+ writeInt(&buf, Int32(1))
+
+
+ case .connecting:
+ writeInt(&buf, Int32(2))
+
+
+ case .connect:
+ writeInt(&buf, Int32(3))
+
+
+ case .status:
+ writeInt(&buf, Int32(4))
+
+ }
+ }
+}
+
+
+#if swift(>=5.8)
+@_documentation(visibility: private)
+#endif
+public func FfiConverterTypeAppDesktopCoverKind_lift(_ buf: RustBuffer) throws -> AppDesktopCoverKind {
+ return try FfiConverterTypeAppDesktopCoverKind.lift(buf)
+}
+
+#if swift(>=5.8)
+@_documentation(visibility: private)
+#endif
+public func FfiConverterTypeAppDesktopCoverKind_lower(_ value: AppDesktopCoverKind) -> RustBuffer {
+ return FfiConverterTypeAppDesktopCoverKind.lower(value)
+}
+
+
// Note that we don't yet support `indirect` for enums.
// See https://github.com/mozilla/uniffi-rs/issues/396 for further discussion.
@@ -45754,6 +46166,119 @@ public func FfiConverterTypeAppStorageRequest_lower(_ value: AppStorageRequest)
}
+// Note that we don't yet support `indirect` for enums.
+// See https://github.com/mozilla/uniffi-rs/issues/396 for further discussion.
+
+public enum AppStreamPhase: Equatable, Hashable {
+
+ /**
+ * No session yet.
+ */
+ case noSession
+ /**
+ * A session that has not started.
+ */
+ case idle
+ /**
+ * Opening (no frame yet).
+ */
+ case connecting
+ /**
+ * Frames arrive.
+ */
+ case streaming
+ /**
+ * Paused by the Space (the stream view says why).
+ */
+ case suspended
+ /**
+ * It could not open.
+ */
+ case failed
+
+
+
+
+
+}
+
+#if compiler(>=6)
+extension AppStreamPhase: Sendable {}
+#endif
+
+#if swift(>=5.8)
+@_documentation(visibility: private)
+#endif
+public struct FfiConverterTypeAppStreamPhase: FfiConverterRustBuffer {
+ typealias SwiftType = AppStreamPhase
+
+ public static func read(from buf: inout (data: Data, offset: Data.Index)) throws -> AppStreamPhase {
+ let variant: Int32 = try readInt(&buf)
+ switch variant {
+
+ case 1: return .noSession
+
+ case 2: return .idle
+
+ case 3: return .connecting
+
+ case 4: return .streaming
+
+ case 5: return .suspended
+
+ case 6: return .failed
+
+ default: throw UniffiInternalError.unexpectedEnumCase
+ }
+ }
+
+ public static func write(_ value: AppStreamPhase, into buf: inout [UInt8]) {
+ switch value {
+
+
+ case .noSession:
+ writeInt(&buf, Int32(1))
+
+
+ case .idle:
+ writeInt(&buf, Int32(2))
+
+
+ case .connecting:
+ writeInt(&buf, Int32(3))
+
+
+ case .streaming:
+ writeInt(&buf, Int32(4))
+
+
+ case .suspended:
+ writeInt(&buf, Int32(5))
+
+
+ case .failed:
+ writeInt(&buf, Int32(6))
+
+ }
+ }
+}
+
+
+#if swift(>=5.8)
+@_documentation(visibility: private)
+#endif
+public func FfiConverterTypeAppStreamPhase_lift(_ buf: RustBuffer) throws -> AppStreamPhase {
+ return try FfiConverterTypeAppStreamPhase.lift(buf)
+}
+
+#if swift(>=5.8)
+@_documentation(visibility: private)
+#endif
+public func FfiConverterTypeAppStreamPhase_lower(_ value: AppStreamPhase) -> RustBuffer {
+ return FfiConverterTypeAppStreamPhase.lower(value)
+}
+
+
// Note that we don't yet support `indirect` for enums.
// See https://github.com/mozilla/uniffi-rs/issues/396 for further discussion.
@@ -56350,6 +56875,17 @@ public func appDeleteFailedText(name: String, error: String) -> String {
)
})
}
+/**
+ * What a Space's preview card shows before (or instead of) its live
+ * desktop: "Connecting…", a Connect button, or the Space's own line.
+ */
+public func appDesktopCover(input: AppDesktopCoverInput) -> AppDesktopCover {
+ return try! FfiConverterTypeAppDesktopCover_lift(try! rustCall() {
+ uniffi_cua_spaces_ffi_fn_func_app_desktop_cover(
+ FfiConverterTypeAppDesktopCoverInput_lower(input),$0
+ )
+})
+}
/**
* A device name as typed for Rename (`None` when empty).
*/
@@ -58134,6 +58670,15 @@ public func appThisMachineSpace(status: AppHostSummaryInput?, nowMs: Int64) -> A
)
})
}
+/**
+ * How fresh the shells keep each Space's thumbnail.
+ */
+public func appThumbnailPolicy() -> AppThumbnailPolicy {
+ return try! FfiConverterTypeAppThumbnailPolicy_lift(try! rustCall() {
+ uniffi_cua_spaces_ffi_fn_func_app_thumbnail_policy($0
+ )
+})
+}
/**
* Advances the transfer overlay (`None` hides it).
*/
@@ -58735,6 +59280,9 @@ private let initializationResult: InitializationResult = {
if (uniffi_cua_spaces_ffi_checksum_func_app_delete_failed_text() != 11381) {
return InitializationResult.apiChecksumMismatch
}
+ if (uniffi_cua_spaces_ffi_checksum_func_app_desktop_cover() != 7825) {
+ return InitializationResult.apiChecksumMismatch
+ }
if (uniffi_cua_spaces_ffi_checksum_func_app_devices_clean_name() != 62073) {
return InitializationResult.apiChecksumMismatch
}
@@ -59236,6 +59784,9 @@ private let initializationResult: InitializationResult = {
if (uniffi_cua_spaces_ffi_checksum_func_app_this_machine_space() != 14017) {
return InitializationResult.apiChecksumMismatch
}
+ if (uniffi_cua_spaces_ffi_checksum_func_app_thumbnail_policy() != 18561) {
+ return InitializationResult.apiChecksumMismatch
+ }
if (uniffi_cua_spaces_ffi_checksum_func_app_transfer_reduce() != 56658) {
return InitializationResult.apiChecksumMismatch
}
diff --git a/libs/spaces-app-swift/Sources/cua_spaces_ffiFFI/include/cua_spaces_ffiFFI.h b/libs/spaces-app-swift/Sources/cua_spaces_ffiFFI/include/cua_spaces_ffiFFI.h
index 29375604f8..cde6c6b034 100644
--- a/libs/spaces-app-swift/Sources/cua_spaces_ffiFFI/include/cua_spaces_ffiFFI.h
+++ b/libs/spaces-app-swift/Sources/cua_spaces_ffiFFI/include/cua_spaces_ffiFFI.h
@@ -882,6 +882,11 @@ RustBuffer uniffi_cua_spaces_ffi_fn_func_app_daemon_check_from_json(RustBuffer j
RustBuffer uniffi_cua_spaces_ffi_fn_func_app_delete_failed_text(RustBuffer name, RustBuffer error, RustCallStatus *_Nonnull out_status
);
#endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_CUA_SPACES_FFI_FN_FUNC_APP_DESKTOP_COVER
+#define UNIFFI_FFIDEF_UNIFFI_CUA_SPACES_FFI_FN_FUNC_APP_DESKTOP_COVER
+RustBuffer uniffi_cua_spaces_ffi_fn_func_app_desktop_cover(RustBuffer input, RustCallStatus *_Nonnull out_status
+);
+#endif
#ifndef UNIFFI_FFIDEF_UNIFFI_CUA_SPACES_FFI_FN_FUNC_APP_DEVICES_CLEAN_NAME
#define UNIFFI_FFIDEF_UNIFFI_CUA_SPACES_FFI_FN_FUNC_APP_DEVICES_CLEAN_NAME
RustBuffer uniffi_cua_spaces_ffi_fn_func_app_devices_clean_name(RustBuffer name, RustCallStatus *_Nonnull out_status
@@ -1733,6 +1738,12 @@ RustBuffer uniffi_cua_spaces_ffi_fn_func_app_teleport_run_status(RustBuffer even
#ifndef UNIFFI_FFIDEF_UNIFFI_CUA_SPACES_FFI_FN_FUNC_APP_THIS_MACHINE_SPACE
#define UNIFFI_FFIDEF_UNIFFI_CUA_SPACES_FFI_FN_FUNC_APP_THIS_MACHINE_SPACE
RustBuffer uniffi_cua_spaces_ffi_fn_func_app_this_machine_space(RustBuffer status, int64_t now_ms, RustCallStatus *_Nonnull out_status
+);
+#endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_CUA_SPACES_FFI_FN_FUNC_APP_THUMBNAIL_POLICY
+#define UNIFFI_FFIDEF_UNIFFI_CUA_SPACES_FFI_FN_FUNC_APP_THUMBNAIL_POLICY
+RustBuffer uniffi_cua_spaces_ffi_fn_func_app_thumbnail_policy(RustCallStatus *_Nonnull out_status
+
);
#endif
#ifndef UNIFFI_FFIDEF_UNIFFI_CUA_SPACES_FFI_FN_FUNC_APP_TRANSFER_REDUCE
@@ -2472,6 +2483,12 @@ uint16_t uniffi_cua_spaces_ffi_checksum_func_app_daemon_check_from_json(void
#define UNIFFI_FFIDEF_UNIFFI_CUA_SPACES_FFI_CHECKSUM_FUNC_APP_DELETE_FAILED_TEXT
uint16_t uniffi_cua_spaces_ffi_checksum_func_app_delete_failed_text(void
+);
+#endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_CUA_SPACES_FFI_CHECKSUM_FUNC_APP_DESKTOP_COVER
+#define UNIFFI_FFIDEF_UNIFFI_CUA_SPACES_FFI_CHECKSUM_FUNC_APP_DESKTOP_COVER
+uint16_t uniffi_cua_spaces_ffi_checksum_func_app_desktop_cover(void
+
);
#endif
#ifndef UNIFFI_FFIDEF_UNIFFI_CUA_SPACES_FFI_CHECKSUM_FUNC_APP_DEVICES_CLEAN_NAME
@@ -3474,6 +3491,12 @@ uint16_t uniffi_cua_spaces_ffi_checksum_func_app_teleport_run_status(void
#define UNIFFI_FFIDEF_UNIFFI_CUA_SPACES_FFI_CHECKSUM_FUNC_APP_THIS_MACHINE_SPACE
uint16_t uniffi_cua_spaces_ffi_checksum_func_app_this_machine_space(void
+);
+#endif
+#ifndef UNIFFI_FFIDEF_UNIFFI_CUA_SPACES_FFI_CHECKSUM_FUNC_APP_THUMBNAIL_POLICY
+#define UNIFFI_FFIDEF_UNIFFI_CUA_SPACES_FFI_CHECKSUM_FUNC_APP_THUMBNAIL_POLICY
+uint16_t uniffi_cua_spaces_ffi_checksum_func_app_thumbnail_policy(void
+
);
#endif
#ifndef UNIFFI_FFIDEF_UNIFFI_CUA_SPACES_FFI_CHECKSUM_FUNC_APP_TRANSFER_REDUCE
diff --git a/scripts/docs-generators/cua-sdk.ts b/scripts/docs-generators/cua-sdk.ts
index e088f86340..1cef31cd4f 100644
--- a/scripts/docs-generators/cua-sdk.ts
+++ b/scripts/docs-generators/cua-sdk.ts
@@ -597,11 +597,11 @@ export const PAGES: PageSpec[] = [
slug: 'spaces/windows',
title: 'Windows, icons and displays',
description: 'A Space\'s app icons (batched, through the SDK\'s one icon cache), window previews, displays and memory and storage use.',
- intro: '`app_icons` answers a whole window list in one call: cached icons come from memory or `$CUA_HOME/cache/icons`, and every miss costs one guest round trip. `window_thumbnail` previews one window, reused for a few seconds. `displays` lists the displays with their resolution and `usage` the memory and storage use.',
+ intro: '`app_icons` answers a whole window list in one call: cached icons come from memory or `$CUA_HOME/cache/icons`, and every miss costs one guest round trip. `thumbnail` is the Space\'s latest small preview from the cache every client on the machine shares (`$CUA_HOME/cache/thumbnails`, kept fresh by the daemon while someone asks). `window_thumbnail` previews one window, reused for a few seconds. `displays` lists the displays with their resolution and `usage` the memory and storage use.',
members: [
- { object: 'Space', title: 'Windows, icons and displays', methods: ['app_icons', 'app_icon', 'window_thumbnail', 'displays', 'usage'] },
+ { object: 'Space', title: 'Windows, icons and displays', methods: ['app_icons', 'app_icon', 'thumbnail', 'window_thumbnail', 'displays', 'usage'] },
],
- items: ['SpaceAppIcon', 'SpaceAppIconRequest', 'SpaceDisplay', 'SpaceUsage'],
+ items: ['SpaceAppIcon', 'SpaceAppIconRequest', 'SpaceDisplay', 'SpaceThumbnail', 'SpaceUsage'],
},
{
slug: 'spaces/agents',
@@ -770,8 +770,20 @@ export const PAGES: PageSpec[] = [
slug: 'spaces/app-core/stream',
title: 'Stream section and facts',
description: 'A Space detail\'s Stream rows (desktop and windows with their icons and picture in picture) and its facts with live memory and storage use.',
- intro: '`app_stream_section` builds the Stream rows both apps draw: the Desktop with the OS mark and the display\'s resolution, then one row per window titled by the window, with the app\'s icon source and a picture-in-picture button. `app_space_detail_live` adds Memory and Storage to the facts from `Space.usage`.',
- items: ['app_space_detail_live', 'AppSpaceUsage', 'app_usage_refresh_ms', 'AppPipCommand', 'AppPipEvent'],
+ intro: '`app_stream_section` builds the Stream rows both apps draw: the Desktop with the OS mark and the display\'s resolution, then one row per window titled by the window, with the app\'s icon source and a picture-in-picture button. `app_space_detail_live` adds Memory and Storage to the facts from `Space.usage`. `app_desktop_cover` says what the preview card shows before the first frame (Connecting, a Connect button, or the Space\'s own line) and `app_thumbnail_policy` how fresh the shells keep its blurred preview.',
+ items: [
+ 'app_space_detail_live',
+ 'AppSpaceUsage',
+ 'app_usage_refresh_ms',
+ 'AppPipCommand',
+ 'AppPipEvent',
+ 'app_desktop_cover',
+ 'AppDesktopCover',
+ 'AppDesktopCoverInput',
+ 'AppDesktopCoverKind',
+ 'app_thumbnail_policy',
+ 'AppThumbnailPolicy',
+ ],
prefixes: ['AppStream', 'app_stream_'],
spaces: true,
},