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_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> |
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. |
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