Stream section and facts
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.
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.
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.
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#The selected Space's detail with its memory and storage use (the SDK's
Space.usage, refreshed every app_usage_refresh_ms). host_arch is
this Mac's CPU architecture (arm64, x86_64): a local Space of
another one shows a warning on its Architecture.
func appSpaceDetailLive(space: AppSpace, usage: AppSpaceUsage?, hostArch: String?) -> AppSpaceDetail| Parameter | Type | Default |
|---|---|---|
space | AppSpace | required |
usage | Option<AppSpaceUsage> | required |
host_arch | Option<String> | required |
Returns AppSpaceDetail
AppSpaceUsage record#| Field | Type | Default | Description |
|---|---|---|---|
memory_used / memoryUsed | u64 | Memory in use, bytes. | |
memory_total / memoryTotal | u64 | Memory size, bytes. | |
memory_limited / memoryLimited | bool | memory_total is the guest's limit. | |
disk_used / diskUsed | u64 | Storage in use, bytes. | |
disk_total / diskTotal | u64 | Storage size, bytes. | |
disk_limited / diskLimited | bool | disk_total is the guest's own disk. |
app_usage_refresh_ms#How often a shell refreshes a visible detail's memory and storage use.
func appUsageRefreshMs() -> UInt64Returns u64
AppPipCommand enum#.open(row: String)
.close(row: String)| Variant | Description |
|---|---|
Open | Open the row's panel. Fields: row: String |
Close | Close the row's open panel. Fields: row: String |
AppPipEvent enum#.opened(row: String)
.closed(row: String)
.synced(rows: [String])| Variant | Description |
|---|---|
Opened | A row's panel opened. Fields: row: 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.
func appDesktopCover(input: AppDesktopCoverInput) -> AppDesktopCover| Parameter | Type | Default |
|---|---|---|
input | AppDesktopCoverInput | required |
Returns AppDesktopCover
AppDesktopCover record#Returned by app_desktop_cover.
| Field | Type | Default | Description |
|---|---|---|---|
kind | AppDesktopCoverKind | 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). | |
button_disabled / buttonDisabled | bool | The button shows greyed out (Connect while this device is not enrolled). | |
action | Option<String> | The one action above a greyed-out Connect ("Enroll This Mac…"): the shell opens the enroll sheet. |
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 | The shell's stream session. | |
access | Option<AppMachineAccessNotice> | The detail's access: this device is signed in but not enrolled, so Connect shows greyed out under this notice and its action. |
AppDesktopCoverKind enum#.stream
.connecting
.connect
.status| 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.
func appThumbnailPolicy() -> AppThumbnailPolicyReturns AppThumbnailPolicy
AppThumbnailPolicy record#Returned by 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 |
|---|---|---|---|
width_px / widthPx | u32 | Width, px. | |
height_px / heightPx | u32 | Height, px. |
AppStreamRow record#| Field | Type | Default | Description |
|---|---|---|---|
id | String | DESKTOP_ROW_ID or the window's handle. | |
kind | AppStreamRowKind | Desktop or window. | |
label | String | The one line ("Desktop (1280×800)", a window's title). | |
help | String | The full label, for the tooltip when it is truncated. | |
resolution | Option<String> | The display's resolution ("1280×800"), Desktop row only. | |
icon | AppStreamRowIcon | The icon. | |
actions | Vec<AppStreamRowAction> | Icon buttons, in order. |
AppStreamRowAction record#| Field | Type | Default | Description |
|---|---|---|---|
id | AppStreamRowActionId | What it does. | |
symbol | String | SF Symbol (pip.enter, pip.exit while open). | |
help | String | Tooltip and accessibility label. | |
active | bool | Its panel is open. |
AppStreamSection record#Returned by app_stream_section.
| Field | Type | Default | Description |
|---|---|---|---|
rows | Vec<AppStreamRow> | The Desktop row, then one per window. | |
status_text / statusText | Option<String> | Under the rows while there are no window rows: loading, none, failed or no match. |
AppStreamSectionInput record#| Field | Type | Default | Description |
|---|---|---|---|
windows | Option<Vec<AppRemoteWindow>> | The Space's windows, None while they load. | |
failed | bool | The window list could not be read. | |
display | Option<AppStreamDisplay> | The primary display, when the display list has been read. | |
os | AppSpaceOs | The Space's OS (the Desktop row's icon). | |
os_name / osName | Option<String> | The OS name the Space reported ("Ubuntu 24.04"), if any. | |
open | Vec<String> | Rows whose picture in picture is open (row ids). | |
query | String | Filter text. |
AppStreamPhase enum#.noSession
.idle
.connecting
.reconnecting
.streaming
.suspended
.failed| Variant | Description |
|---|---|
NoSession | No session yet. |
Idle | A session that has not started. |
Connecting | Opening (no frame yet). |
Reconnecting | Opening again by itself after the stream dropped (no frame yet). |
Streaming | Frames arrive. |
Suspended | Paused by the Space (the stream view says why). |
Failed | It could not open. |
AppStreamRowActionId enum#.pip| Variant | Description |
|---|---|
Pip | Picture in picture: the row's own stream in a floating panel. |
AppStreamRowIcon enum#.os(id: String)
.app(appName: String, appId: String, pid: UInt32)| Variant | Description |
|---|---|
Os | The Space's OS mark (os-ubuntu, os-windows, ...): the core's artwork (notch.osIconSvg) or system symbol. Fields: id: String |
App | The app's icon from the SDK's Space.app_icon (these three arguments); none when the Space has none. Fields: app_name: String, app_id: String, pid: u32 |
AppStreamRowKind enum#.desktop
.window| Variant | Description |
|---|---|
Desktop | The whole desktop. |
Window | One window. |
app_stream_desktop_row_id#The Stream section's Desktop row id (a window row's id is its handle).
func appStreamDesktopRowId() -> StringReturns String
app_stream_pip_click#What a row's picture-in-picture button does: close its open panel, or open one.
func appStreamPipClick(open: [String], row: String) -> AppPipCommand| Parameter | Type | Default |
|---|---|---|
open | Vec<String> | required |
row | String | required |
Returns AppPipCommand
app_stream_pip_reduce#The open picture-in-picture panels (row ids) after a panel opened,
closed or the shell re-read them: the Stream section's open.
func appStreamPipReduce(open: [String], event: AppPipEvent) -> [String]| Parameter | Type | Default |
|---|---|---|
open | Vec<String> | required |
event | AppPipEvent | required |
Returns Vec<String>
app_stream_section#A Space's Stream section: the Desktop row, then one row per window.
func appStreamSection(input: AppStreamSectionInput) -> AppStreamSection| Parameter | Type | Default |
|---|---|---|
input | AppStreamSectionInput | required |
Returns AppStreamSection