Window, menu bar and Settings

The window chrome, a Space's toolbar and sections, the menu bar menu and Settings.

Cua Spaces app export

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_main_chrome, app_menu_bar and app_settings_page give the window chrome, the menu bar menu and the Settings page. app_space_detail_copy holds the words of a Space's sections. The coding agents' rows of Settings are on Settings, Agents. app_login_item_launch_plan decides when the apps turn on launch at login by themselves.

`app_display_name`#

A Space name as shown: as typed, trimmed.

func appDisplayName(name: String) -> String

Parameter	Type	Default
`name`	`String`	required

Returns String

`app_display_path`#

Home-relative path (~/x).

func appDisplayPath(path: String, home: String?) -> String

Parameter	Type	Default
`path`	`String`	required
`home`	`Option<String>`	required

Returns String

`app_format_bytes`#

"12 MB".

func appFormatBytes(bytes: UInt64) -> String

Parameter	Type	Default
`bytes`	`u64`	required

Returns String

`AppFact` record#

Field	Type	Description
`label`	`String`	Label.
`value`	`String`	Value.
`copy`	`Option<AppFactCopy>`	A copy button after the value (the Space's identifier and image).
`help`	`Option<String>`	The tooltip: the full value (and an image's digest).
`warning`	`Option<AppFactWarning>`	A warning symbol after the value, with its tooltip: a local Space emulating another architecture.

`AppFactCopy` record#

Field	Type	Description
`text`	`String`	What is copied (the full value).
`symbol`	`String`	SF Symbol (`doc.on.doc`).
`help`	`String`	Tooltip and accessibility label ("Copy").
`done_symbol` / `doneSymbol`	`String`	The symbol while confirming (`checkmark`).
`done_help` / `doneHelp`	`String`	The tooltip while confirming ("Copied").
`confirm_ms` / `confirmMs`	`u32`	How long the confirmation shows, in milliseconds.

`app_delete_failed_text`#

The banner when Delete fails.

func appDeleteFailedText(name: String, error: String) -> String

Parameter	Type	Default
`name`	`String`	required
`error`	`String`	required

Returns String

`AppDetailCopy` record#

Returned by app_space_detail_copy.

Field	Type	Description
`stream_loading` / `streamLoading`	`String`	"Looking for this Space's windows…"
`stream_empty` / `streamEmpty`	`String`	"No open windows in this Space yet."
`stream_failed` / `streamFailed`	`String`	When the window list could not be read.
`stream_no_match` / `streamNoMatch`	`String`	When a filter hides every window.
`agents_loading` / `agentsLoading`	`String`	"Looking for this Space's agents…"
`agents_empty` / `agentsEmpty`	`String`	"No agents have been started in this Space."
`agents_failed` / `agentsFailed`	`String`	When the runs could not be read (not the same as none).
`agents_no_match` / `agentsNoMatch`	`String`	When a filter hides every run.
`drop_caption` / `dropCaption`	`String`	The drop well's caption.
`send_file` / `sendFile`	`String`	"Send file…"
`teleport_app` / `teleportApp`	`String`	"Teleport an app…"
`teleport_symbol` / `teleportSymbol`	`String`	The teleport icon (`TELEPORT_SYMBOL`).
`teleport_symbol_active` / `teleportSymbolActive`	`String`	The teleport icon while a drag is over a drop target.

`app_space_detail_copy`#

The words of a Space's sections (Stream, Agents, Teleport).

func appSpaceDetailCopy() -> AppDetailCopy

Returns AppDetailCopy

`AppDetailAction` record#

Field	Type	Description
`id`	`AppDetailActionId`	What it does.
`label`	`String`	Label.
`symbol`	`Option<String>`	SF Symbol (icon buttons).
`help`	`String`	Tooltip.
`enabled`	`bool`	Enabled.
`destructive`	`bool`	Drawn as destructive.
`primary`	`bool`	The prominent one.
`busy`	`bool`	Its action runs: a spinner in place of the icon.

`AppDetailActionId` enum#

.teleport
.pip
.share
.power
.delete
.open
.cancel

Variant	Description
`Teleport`	"Teleport an app…" into the Space.
`Pip`	The desktop in a picture-in-picture panel.
`Share`	"Share": let another cua.ai account watch or edit the Space.
`Power`	Turn it off or on (the power button, next to Delete).
`Delete`	Delete (or remove from the list).
`Open`	The desktop in its own window.
`Cancel`	Stop a create that is still running and remove what it made.

`AppDeleteConfirm` record#

Field	Type	Description
`title`	`String`	"Delete Brave Otter?"
`message`	`String`	What it means, one line.
`confirm_label` / `confirmLabel`	`String`	The destructive button.
`confirm_enabled` / `confirmEnabled`	`bool`	The destructive button can be pressed (a Space in your cloud that another device created cannot be deleted from here).
`disabled_reason` / `disabledReason`	`Option<String>`	Why not, beside the disabled button.
`remove_label` / `removeLabel`	`Option<String>`	For a Space in your cloud: "Remove from List", which forgets it and keeps it running there (`remove_space`).
`cancel_label` / `cancelLabel`	`String`	"Keep" (or "Cancel" beside Remove from List).

`AppSentFileInfo` record#

Returned by app_sent_file, app_sent_files_from_json.

Field	Type	Description
`name`	`String`	File name.
`dest`	`String`	Where it landed in the Space.
`bytes`	`u64`	Bytes.

`app_sent_file`#

A send_file report as the files the drop well names.

func appSentFile(report: SpaceSendFileReport) -> AppSentFileInfo

Parameter	Type	Default
`report`	`SpaceSendFileReport`	required

Returns AppSentFileInfo

`app_sent_files_from_json`#

Sent files from JSON (parity flows).

func appSentFilesFromJson(json: String) throws -> [AppSentFileInfo]

Parameter	Type	Default
`json`	`String`	required

Returns Vec<AppSentFileInfo> · Raises CuaError

`app_drop_sending_text`#

The drop well's line while files go.

func appDropSendingText(paths: [String]) -> String

Parameter	Type	Default
`paths`	`Vec<String>`	required

Returns String

`app_drop_sent_text`#

The drop well's line once they landed.

func appDropSentText(files: [AppSentFileInfo]) -> String

Parameter	Type	Default
`files`	`Vec<AppSentFileInfo>`	required

Returns String

`AppSignInPhase` enum#

.idle
.starting
.waiting(userCode: String?)
.failed(message: String)

Variant	Description
`Idle`	Nothing started.
`Starting`	Asking for a code.
`Waiting`	The browser is open. Fields: `user_code: Option<String>`
`Failed`	It failed. Fields: `message: String`

`AppTelemetryInput` record#

Field	Type	Description
`enabled`	`bool`	Usage data is shared.
`locked_by` / `lockedBy`	`Option<String>`	The environment decides (`DO_NOT_TRACK`, `CUA_TELEMETRY`, CI): who.
`notice_shown` / `noticeShown`	`bool`	The first-run usage notice was already shown on this machine (by `cua`, or an earlier run of the app): events may be sent before Welcome is left.

`app_menu`#

The menu bar item's menu: the Spaces the user can open (the notch's count), Cua Volume's sync state next to it and its conflicts, then the actions.

func appMenu(input: AppMenuInput) -> [AppMenuItem]

Parameter	Type	Default
`input`	`AppMenuInput`	required

Returns Vec<AppMenuItem>

`AppMenuInput` record#

Returned by app_menu_input_from_json.

Field	Type	Description
`spaces`	`Vec<AppSpace>`	The roster (with "This machine").
`keyvault`	`Option<String>`	Live Keyvault sign-ins (`crate.keyvault.view.sharing_label`).
`sync`	`Option<AppDriveSyncInput>`	Cua Volume's `volume_sync_status`, when read.
`now_ms` / `nowMs`	`u64`	Now (Unix ms): a feed that has not answered for `OFFLINE_AFTER_MS` is offline.
`backend`	`Option<String>`	`volume_storage`'s backend (`fs`, `s3`), when read: this machine's store with no other device has nothing to sync.
`experiments`	`Option<AppExperiments>`	Settings, Experiments: Cua Volume's sync state and conflicts only with Cua Volume on (none: shown, for callers that predate experiments). Off hides them; the volume keeps syncing.

`app_menu_input_from_json`#

The menu bar item's menu input from JSON (fixtures, parity).

func appMenuInputFromJson(json: String) throws -> AppMenuInput

Parameter	Type	Default
`json`	`String`	required

Returns AppMenuInput · Raises CuaError

`app_openable_count`#

The Spaces the user can open (the notch tab and the menu bar item).

func appOpenableCount(spaces: [AppSpace]) -> UInt32

Parameter	Type	Default
`spaces`	`Vec<AppSpace>`	required

Returns u32

`AppChromeInput` record#

Returned by app_chrome_input_from_json.

Field	Type	Description
`identity`	`Option<String>`	The signed-in account.
`cloud_configured` / `cloudConfigured`	`bool`	Cua Cloud works (signed in, or client credentials).
`can_sign_in` / `canSignIn`	`bool`	Signing in is possible here (the native shell).
`experiments`	`Option<AppExperiments>`	Settings, Experiments: the Volume page only with Cua Volume on (none: every page, for callers that predate experiments).

`AppLoginItemInput` record#

Field	Type	Description
`status`	`AppLoginItemStatus`	What the system reports.
`busy`	`bool`	A change is running.
`error`	`Option<String>`	Why the last change failed.
`provides_spaces` / `providesSpaces`	`bool`	This machine provides Spaces to your other devices (host setup's "A spare machine for Spaces").
`runs_agents` / `runsAgents`	`bool`	This machine runs persistent agents.

`AppLoginItemPlan` record#

Returned by app_login_item_launch_plan.

Field	Type	Default	Description
`register`	`bool`		Register the app as a login item now.
`record`	`Option<bool>`		Save this as the user's choice (`AppSettings::launch_at_login`).

`AppMainChrome` record#

Returned by app_main_chrome.

Field	Type	Description
`title`	`String`	Window title when nothing is selected.
`new_space_label` / `newSpaceLabel`	`String`	"New Space".
`new_space_shortcut` / `newSpaceShortcut`	`String`	"⌘N".
`search_placeholder` / `searchPlaceholder`	`String`	The sidebar search's placeholder.
`keyvault_title` / `keyvaultTitle`	`String`	The Keyvault section's title.
`account`	`String`	The account line: the identity, "API key" or "Not signed in".
`sign_in_label` / `signInLabel`	`Option<String>`	"Sign in", when signing in is offered.
`settings_label` / `settingsLabel`	`String`	"Settings".
`settings_shortcut` / `settingsShortcut`	`String`	"⌘,".
`empty_title` / `emptyTitle`	`String`	With no Spaces: the heading.
`empty_action` / `emptyAction`	`String`	With no Spaces: the default Linux Space's tile.
`empty_linux_detail` / `emptyLinuxDetail`	`String`	Under it: the time and disk.
`empty_detail` / `emptyDetail`	`String`	With no Spaces: the line under the heading.
`empty_macos_action` / `emptyMacosAction`	`String`	With no Spaces: the default macOS Space's tile.
`empty_macos_detail` / `emptyMacosDetail`	`String`	Under it: the download size.
`volume_label` / `volumeLabel`	`Option<String>`	The sidebar's Volume page entry ("Volume"); none while the Cua Volume experiment is off (the page and its route are hidden; a mounted volume stays mounted).

`AppMenuItem` record#

Returned by app_menu, app_menu_bar, app_menu_bar_with_keyvault.

Field	Type	Description
`id`	`AppMenuItemId`	What it does.
`label`	`String`	Label (empty for a separator).
`shortcut`	`Option<String>`	"⌘,", "⌘Q".
`enabled`	`bool`	Enabled.

`AppSettingsInput` record#

Returned by app_settings_input_from_json.

Field	Type	Description
`identity`	`Option<String>`	The signed-in account.
`api_key_client` / `apiKeyClient`	`Option<String>`	Cua Cloud through client credentials (an API key): its client id.
`sign_in` / `signIn`	`AppSignInPhase`	The sign-in in progress.
`can_sign_out` / `canSignOut`	`bool`	Signing out is possible (a user session).
`menu_bar` / `menuBar`	`bool`	The Spaces tab is hidden from the notch (the menu bar item is the entry point).
`default_location` / `defaultLocation`	`AppLocation`	Where New Space starts.
`location_locked_by` / `locationLockedBy`	`Option<String>`	The environment sets the default location: which variable.
`telemetry`	`Option<AppTelemetryInput>`	The telemetry switch (none until read).
`agents`	`Option<Vec<AppAgentSettingsRow>>`	Coding agents (none while detecting).
`agents_busy` / `agentsBusy`	`bool`	"Configure all" is running.
`agents_pending` / `agentsPending`	`Vec<String>`	Agents with an action running.
`teams`	`Option<AppTeamsInput>`	Teams from the Spaces API (the host reads them), with the account app's URL. None: the Teams section shows the production account app's links only.
`billing`	`Option<AppBillingStatus>`	The account's Cua Cloud billing, once read (signed in).
`login_item` / `loginItem`	`Option<AppLoginItemInput>`	Launch at login, once the system was asked (none: no rows).
`experiments`	`AppExperiments`	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).
`keyvault_unlock_prompt` / `keyvaultUnlockPrompt`	`Option<bool>`	The unlock prompt shows (false once the user chose "Never ask again"); none until the broker told it.
`keyvault_site_icons` / `keyvaultSiteIcons`	`bool`	Load site icons from Google when the browser had none (`AppSettings.keyvault_site_icons`).
`keyvault_protection` / `keyvaultProtection`	`Vec<AppFact>`	The Keyvault's protection facts (Touch ID, the daemon's signature), shown in the section.
`auto_connect` / `autoConnect`	`Option<bool>`	"Connect to the desktop automatically" (none: no row; a shell without the preview cover leaves it out).
`lume_source` / `lumeSource`	`Option<String>`	Which Lume macOS Spaces run on (`runtime.lume`: `auto`, `builtin`, `system`); none: no Runtimes section.
`linux_source` / `linuxSource`	`Option<String>`	Which engine local Linux Spaces run on (`runtime.linux`: `auto`, `builtin`, `system`); none: no Linux row.

`AppSettingsOption` record#

Field	Type	Description
`id`	`String`	`show`, `hide`, `local`, `cloud`, `on`, `off`.
`label`	`String`	Label.
`active`	`bool`	Chosen.

`AppSettingsPage` record#

Returned by app_experiments_page, app_settings_page, app_settings_with_storage.

Field	Type	Default	Description
`title`	`String`		"Settings".
`sections`	`Vec<AppSettingsSection>`		Account, General, Privacy (once read), AI agents.

`AppSettingsRow` record#

Field	Type	Description
`id`	`String`	Stable id (`account`, `sign-in`, `notch`, `agent:codex`, ...).
`kind`	`AppSettingsRowKind`	How it draws.
`label`	`String`	Label (or the note's text).
`value`	`Option<String>`	Muted value.
`button`	`Option<String>`	A button's label.
`options`	`Vec<AppSettingsOption>`	A choice's options.
`enabled`	`bool`	The button or choice can be used.
`help`	`Option<String>`	Tooltip.
`link_label` / `linkLabel`	`Option<String>`	A note's link: label.
`link_url` / `linkUrl`	`Option<String>`	A note's link: URL (or what a Text row's button opens).
`placeholder`	`Option<String>`	A field's placeholder.

`AppSettingsSection` record#

Returned by app_storage_section.

Field	Type	Description
`id`	`String`	`account`, `general`, `privacy`, `agents`.
`title`	`String`	"Account", "General", "Privacy", "AI agents".
`button`	`Option<String>`	A button in the header.
`button_enabled` / `buttonEnabled`	`bool`	That button can be used.
`button_help` / `buttonHelp`	`Option<String>`	Its tooltip.
`rows`	`Vec<AppSettingsRow>`	Rows.

`AppLoginItemStatus` enum#

.enabled
.notRegistered
.requiresApproval
.notFound

Variant	Description
`Enabled`	Registered and allowed: the app opens at login.
`NotRegistered`	Not registered.
`RequiresApproval`	Registered, waiting for the user to allow it in System Settings, Login Items.
`NotFound`	The system cannot find the app as a login item.

`AppMenuItemId` enum#

.status
.separator
.open
.newSpace
.settings
.quit
.volumeConflicts

Variant	Description
`Status`	The status line (disabled).
`Separator`	A separator.
`Open`	Show the main window.
`NewSpace`	The New Space sheet.
`Settings`	Settings.
`Quit`	Quit.
`VolumeConflicts`	Cua Volume's conflicts: opens the Volume page.

`AppSettingsRowKind` enum#

.text
.choice
.note
.error
.field
.secret
.prompt
.link
.toggle

Variant	Description
`Text`	Label, value and an optional button.
`Choice`	Label and a segmented choice.
`Note`	A muted line (with an optional link).
`Error`	An error line.
`Field`	Label and a text field (`value` is its text).
`Secret`	Label and a secure text field (`value` is its text).
`Prompt`	A label over read-only text to copy (`value`), with a Copy button.
`Link`	A small link-style button (the label).
`Toggle`	Label and a switch: `options` are `on` and `off`, the active one is its state (a choice drawn as a switch).

`app_chrome_input_from_json`#

The chrome's input from JSON (parity flows).

func appChromeInputFromJson(json: String) throws -> AppChromeInput

Parameter	Type	Default
`json`	`String`	required

Returns AppChromeInput · Raises CuaError

`app_login_item_launch_plan`#

What the app does about launch at login at launch (the user's choice, whether the first run finished, whether this machine provides Spaces or runs persistent agents, and what the system reports).

func appLoginItemLaunchPlan(choice: Bool?, onboarded: Bool, serves: Bool, status: AppLoginItemStatus) -> AppLoginItemPlan

Parameter	Type	Default
`choice`	`Option<bool>`	required
`onboarded`	`bool`	required
`serves`	`bool`	required
`status`	`AppLoginItemStatus`	required

Returns AppLoginItemPlan

`app_main_chrome`#

The main window's chrome (account line, New Space, empty state).

func appMainChrome(input: AppChromeInput) -> AppMainChrome

Parameter	Type	Default
`input`	`AppChromeInput`	required

Returns AppMainChrome

`app_menu_bar`#

The menu bar item's menu.

func appMenuBar(spaces: UInt32) -> [AppMenuItem]

Parameter	Type	Default
`spaces`	`u32`	required

Returns Vec<AppMenuItem>

`app_menu_bar_with_keyvault`#

The menu bar item's menu with the live Keyvault sharing line (kv_sharing_label) when there is one.

func appMenuBarWithKeyvault(spaces: UInt32, keyvault: String?) -> [AppMenuItem]

Parameter	Type	Default
`spaces`	`u32`	required
`keyvault`	`Option<String>`	required

Returns Vec<AppMenuItem>

`app_settings_input_from_json`#

The Settings page's input from JSON (parity flows).

func appSettingsInputFromJson(json: String) throws -> AppSettingsInput

Parameter	Type	Default
`json`	`String`	required

Returns AppSettingsInput · Raises CuaError

`app_settings_page`#

The Settings page.

func appSettingsPage(input: AppSettingsInput) -> AppSettingsPage

Parameter	Type	Default
`input`	`AppSettingsInput`	required

Returns AppSettingsPage

Window, menu bar and Settings

app_display_name#

app_display_path#

app_format_bytes#

AppFact record#

AppFactCopy record#

app_delete_failed_text#

AppDetailCopy record#

app_space_detail_copy#

AppDetailAction record#

AppDetailActionId enum#

AppDeleteConfirm record#

AppSentFileInfo record#

app_sent_file#

app_sent_files_from_json#

app_drop_sending_text#

app_drop_sent_text#

AppSignInPhase enum#

AppTelemetryInput record#

app_menu#

AppMenuInput record#

app_menu_input_from_json#

app_openable_count#

AppChromeInput record#

AppLoginItemInput record#

AppLoginItemPlan record#

AppMainChrome record#

AppMenuItem record#

AppSettingsInput record#

AppSettingsOption record#

AppSettingsPage record#

AppSettingsRow record#

AppSettingsSection record#

AppLoginItemStatus enum#

AppMenuItemId enum#

AppSettingsRowKind enum#

app_chrome_input_from_json#

app_login_item_launch_plan#

app_main_chrome#

app_menu_bar#

app_menu_bar_with_keyvault#

app_settings_input_from_json#

app_settings_page#

app_display_name#

app_display_path#

app_format_bytes#

AppFact record#

AppFactCopy record#

app_delete_failed_text#

AppDetailCopy record#

app_space_detail_copy#

AppDetailAction record#

AppDetailActionId enum#

AppDeleteConfirm record#

AppSentFileInfo record#

app_sent_file#

app_sent_files_from_json#

app_drop_sending_text#

app_drop_sent_text#

AppSignInPhase enum#

AppTelemetryInput record#

app_menu#

AppMenuInput record#

app_menu_input_from_json#

app_openable_count#

AppChromeInput record#

AppLoginItemInput record#

AppLoginItemPlan record#

AppMainChrome record#

AppMenuItem record#

AppSettingsInput record#

AppSettingsOption record#

AppSettingsPage record#

AppSettingsRow record#

AppSettingsSection record#

AppLoginItemStatus enum#

AppMenuItemId enum#

AppSettingsRowKind enum#

app_chrome_input_from_json#

app_login_item_launch_plan#

`app_display_name`#

`app_display_path`#

`app_format_bytes`#

`AppFact` record#

`AppFactCopy` record#

`app_delete_failed_text`#

`AppDetailCopy` record#

`app_space_detail_copy`#

`AppDetailAction` record#

`AppDetailActionId` enum#

`AppDeleteConfirm` record#

`AppSentFileInfo` record#

`app_sent_file`#

`app_sent_files_from_json`#

`app_drop_sending_text`#

`app_drop_sent_text`#

`AppSignInPhase` enum#

`AppTelemetryInput` record#

`app_menu`#

`AppMenuInput` record#

`app_menu_input_from_json`#

`app_openable_count`#

`AppChromeInput` record#

`AppLoginItemInput` record#

`AppLoginItemPlan` record#

`AppMainChrome` record#

`AppMenuItem` record#

`AppSettingsInput` record#

`AppSettingsOption` record#

`AppSettingsPage` record#

`AppSettingsRow` record#

`AppSettingsSection` record#

`AppLoginItemStatus` enum#

`AppMenuItemId` enum#

`AppSettingsRowKind` enum#

`app_chrome_input_from_json`#

`app_login_item_launch_plan`#

`app_main_chrome`#

`app_menu_bar`#

`app_menu_bar_with_keyvault`#

`app_settings_input_from_json`#

`app_settings_page`#

`app_display_name`#

`app_display_path`#

`app_format_bytes`#

`AppFact` record#

`AppFactCopy` record#

`app_delete_failed_text`#

`AppDetailCopy` record#

`app_space_detail_copy`#

`AppDetailAction` record#

`AppDetailActionId` enum#

`AppDeleteConfirm` record#

`AppSentFileInfo` record#

`app_sent_file`#

`app_sent_files_from_json`#

`app_drop_sending_text`#

`app_drop_sent_text`#

`AppSignInPhase` enum#

`AppTelemetryInput` record#

`app_menu`#

`AppMenuInput` record#

`app_menu_input_from_json`#

`app_openable_count`#

`AppChromeInput` record#

`AppLoginItemInput` record#

`AppLoginItemPlan` record#

`AppMainChrome` record#

`AppMenuItem` record#

`AppSettingsInput` record#

`AppSettingsOption` record#

`AppSettingsPage` record#

`AppSettingsRow` record#

`AppSettingsSection` record#

`AppLoginItemStatus` enum#

`AppMenuItemId` enum#

`AppSettingsRowKind` enum#

`app_chrome_input_from_json`#

`app_login_item_launch_plan`#

`app_main_chrome`#