Teleport picker

The teleport picker and review, consent, the transfer overlay and drag-and-drop.

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.

The picker lists Teleport.catalog entries, reviews a Teleport.plan with its consent items, and follows the run. The transfer and drag overlays show a teleport in progress.

`AppEntrySection` record#

Returned by app_picker_sections.

Field	Type	Default	Description
`title`	`String`		"Recent", "Apps", "Not available".
`entries`	`Vec<AppCatalogEntry>`		Entries.

`AppReviewView` record#

Returned by app_picker_review.

Field	Type	Description
`title`	`String`	"Teleport Slack to Aurora".
`items`	`Vec<AppConsentItem>`	The consent lines.
`steps`	`Vec<AppPlanStepView>`	Plan steps.
`needs_acknowledgement` / `needsAcknowledgement`	`bool`	The secrets checkbox shows.
`acknowledged`	`bool`	Checked.
`offers_save_to_keyvault` / `offersSaveToKeyvault`	`bool`	The "Save to Keyvault" checkbox shows (a sensitive plan only: there is nothing to keep sealed otherwise).
`save_to_keyvault` / `saveToKeyvault`	`bool`	Checked.
`needs_relay_plaintext_acknowledgement` / `needsRelayPlaintextAcknowledgement`	`bool`	The relay-plaintext warning's checkbox shows (S1): this Space predates end-to-end sealing, and the Cua relay could read this secret in transit.
`acknowledged_relay_plaintext` / `acknowledgedRelayPlaintext`	`bool`	Checked.
`can_confirm` / `canConfirm`	`bool`	"Teleport" is enabled.
`leaves_text` / `leavesText`	`Option<String>`	"12 MB leaves this Mac" (none when nothing leaves).
`warnings`	`Vec<String>`	Caveats.

`AppPlanStepView` record#

Field	Type	Default	Description
`kind`	`String`		`install`, `files`, `state`, `launch`.
`summary`	`String`		One line.

`AppInstallCuaPrompt` record#

Field	Type	Description
`installed`	`bool`	Cua is installed but not running.
`title`	`String`	Title.
`message`	`String`	One line.
`action_label` / `actionLabel`	`String`	Button.
`url`	`String`	Button target: always one of the constants, never from the error.

`AppCatalogEntry` record#

Returned by app_catalog_entries_from_json, app_catalog_entry.

Field	Type	Description
`id`	`String`	Id.
`name`	`String`	Name.
`host_path` / `hostPath`	`Option<String>`	Bundle path.
`host_app_id` / `hostAppId`	`Option<String>`	Bundle id.
`version`	`Option<String>`	Version.
`capability`	`AppTeleportCapability`	Capability.
`reason`	`Option<String>`	Why unsupported, or a caveat.
`moves`	`Vec<AppTeleportMove>`	Offered moves, UI order.
`provider_id` / `providerId`	`Option<String>`	Provider id.
`sensitive_groups` / `sensitiveGroups`	`Vec<AppSensitiveGroup>`	The opt-in groups the signed-in state move offers, UI order.
`install_source` / `installSource`	`Option<String>`	`manifest`, `image`, `space`.
`install_id` / `installId`	`Option<String>`	Installable id.
`install_version` / `installVersion`	`Option<String>`	Installable version.
`launch_bin` / `launchBin`	`Option<String>`	Binary.
`last_used_ms` / `lastUsedMs`	`Option<i64>`	Last used (recents).
`json`	`String`	The SDK's JSON for this entry.

`AppConsentItem` record#

Field	Type	Description
`kind`	`AppConsentKind`	Kind.
`key`	`String`	Stable key.
`label`	`String`	Label.
`detail`	`String`	Detail.
`bytes`	`u64`	Bytes that leave.
`sensitive`	`bool`	Credentials, cookies, tokens.

`AppDragOverlayState` record#

Field	Type	Description
`phase`	`AppDragOverlayPhase`	Phase.
`window_id` / `windowId`	`Option<u32>`	CoreGraphics id of the dragged window.
`app_name` / `appName`	`Option<String>`	The dragged app's name.
`target_space_id` / `targetSpaceId`	`Option<String>`	The tile under the cursor (selector only).
`ghost`	`Option<String>`	The captured ghost (a data URL or a shell-local image key).

`AppDragOverlayTransition` record#

Field	Type	Default	Description
`state`	`AppDragOverlayState`		New state.
`effects`	`Vec<AppDragOverlayEffect>`		Effects.

`AppPickerPrimary` record#

Returned by app_picker_primary.

Field	Type	Description
`label`	`String`	"Teleport" / "Stream".
`action`	`AppPickerAction`	Action.
`enabled`	`bool`	Enabled.

`AppPickerState` record#

Returned by app_picker_initial, app_picker_reduce.

Field	Type	Description
`step`	`AppPickerStep`	Step.
`space_name` / `spaceName`	`String`	The target Space's name.
`entries`	`Option<Vec<AppCatalogEntry>>`	The catalog, once loaded.
`query`	`String`	Search.
`selected_id` / `selectedId`	`Option<String>`	Highlighted app.
`entry`	`Option<AppCatalogEntry>`	The chosen app.
`moves`	`Option<AppTeleportMove>`	What moves.
`files`	`Vec<String>`	Chosen files.
`sensitive`	`Vec<AppSensitiveGroup>`	The opt-in groups checked on the options step (only planned with the signed-in state move). Each group's items are secrets the review lists and asks to acknowledge.
`plan`	`Option<AppTeleportPlan>`	The plan under review.
`acknowledged`	`bool`	Secrets acknowledged.
`save_to_keyvault` / `saveToKeyvault`	`bool`	"Save to Keyvault" checked: keep the captured session sealed in the Cua Keyvault after delivery, for reuse without asking again (shown alongside the acknowledgement, only when the plan is sensitive).
`acknowledged_relay_plaintext` / `acknowledgedRelayPlaintext`	`bool`	`Plan.relay_unsealed`'s warning acknowledged (S1).
`events`	`Vec<AppTeleportRunEvent>`	Run events (last `MAX_EVENTS`).
`report`	`Option<AppTeleportRunReport>`	The run's report.
`error`	`Option<String>`	Error text.
`install_prompt` / `installPrompt`	`Option<AppInstallCuaPrompt>`	The "needs the Cua app" prompt.
`error_back` / `errorBack`	`AppPickerStep`	Where Back from an error goes.

`AppTeleportConsent` record#

Returned by app_picker_consent.

Field	Type	Description
`approved`	`bool`	Confirmed.
`acknowledge_sensitive` / `acknowledgeSensitive`	`bool`	Secrets acknowledged.
`save_to_keyvault` / `saveToKeyvault`	`bool`	"Save to Keyvault" checked.
`acknowledge_relay_plaintext` / `acknowledgeRelayPlaintext`	`bool`	`Plan.relay_unsealed`'s warning acknowledged (S1).

`AppTeleportPlan` record#

Returned by app_teleport_plan, app_teleport_plan_from_json.

Field	Type	Description
`app`	`AppCatalogEntry`	The app.
`space_id` / `spaceId`	`String`	Target Space.
`moves`	`AppTeleportMove`	What moves.
`steps`	`Vec<AppPlanStepView>`	Steps.
`consent`	`Vec<AppConsentItem>`	Consent lines.
`sensitive`	`bool`	Any line is a secret.
`total_bytes` / `totalBytes`	`u64`	Bytes that leave this machine.
`warnings`	`Vec<String>`	Caveats.
`relay_unsealed` / `relayUnsealed`	`bool`	This Space is reached through a relay connection that predates end-to-end sealing: a secret this plan sends would cross it in the clear (S1). Needs `acknowledgeRelayPlaintext` the same way a secret needs `acknowledgeSensitive`. Defaults to `false`: older fixtures and a plan from a relay that predates the capability both read as sealed (never retroactively flagged).
`json`	`String`	The SDK's JSON for this plan.

`AppTeleportRunEvent` record#

Field	Type	Description
`step`	`u32`	Step index.
`steps`	`u32`	Steps.
`kind`	`String`	Step kind.
`phase`	`AppTeleportRunPhase`	Phase.
`detail`	`String`	Detail.
`done_bytes` / `doneBytes`	`u64`	Bytes done.
`total_bytes` / `totalBytes`	`u64`	Bytes total.

`AppTeleportRunReport` record#

Field	Type	Description
`app_id` / `appId`	`String`	App id.
`installed`	`Vec<String>`	Installed.
`sent`	`Vec<String>`	Sent.
`imported`	`Vec<String>`	Imported.
`skipped`	`Vec<String>`	Skipped.
`launched`	`bool`	Launched.

`AppTransferOverlayState` record#

Returned by app_transfer_reduce.

Field	Type	Description
`phase`	`AppTransferPhase`	Phase.
`app_name` / `appName`	`String`	App being teleported.
`message`	`Option<String>`	Failure reason.
`sent_bytes` / `sentBytes`	`Option<f64>`	Bytes sent.
`total_bytes` / `totalBytes`	`Option<f64>`	Total bytes.

`AppTransferSignal` record#

Field	Type	Description
`status`	`AppTransferStatus`	Status.
`app_name` / `appName`	`Option<String>`	App name.
`message`	`Option<String>`	Message.
`sent_bytes` / `sentBytes`	`Option<f64>`	Bytes sent.
`total_bytes` / `totalBytes`	`Option<f64>`	Total bytes.

`AppConsentKind` enum#

.install
.file
.folder
.state
.secret

Variant	Description
`Install`	An install into the Space.
`File`	A file that leaves this machine.
`Folder`	A folder that leaves this machine.
`State`	App state that leaves this machine.
`Secret`	A secret that leaves this machine.

`AppDragOverlayEffect` enum#

.capture(windowId: UInt32?)
.commit(spaceId: String)

Variant	Description
`Capture`	Capture the ghost (needs Screen Recording; none is fine). Fields: `window_id: Option<u32>`
`Commit`	Teleport to this Space. Fields: `space_id: String`

`AppDragOverlayEvent` enum#

.start(windowId: UInt32?, appName: String?)
.enterNotch
.leaveNotch
.over(spaceId: String)
.out
.ghostReady(ghost: String?)
.drop(spaceId: String?)
.cancel

Variant	Description
`Start`	A supported window drag began. Fields: `window_id: Option<u32>`, `app_name: Option<String>`
`EnterNotch`	The cursor reached the notch box.
`LeaveNotch`	The cursor left the selector.
`Over`	Over a Space tile. Fields: `space_id: String`
`Out`	Off every tile.
`GhostReady`	The ghost capture finished. Fields: `ghost: Option<String>`
`Drop`	Released; the tile under the cursor, if any. Fields: `space_id: Option<String>`
`Cancel`	Abort.

`AppDragOverlayPhase` enum#

.idle
.prompt
.selector

Variant	Description
`Idle`	Nothing showing.
`Prompt`	The "Teleport to Cua" box.
`Selector`	The Space tiles as drop targets.

`AppPickerAction` enum#

.teleport
.streamRemote
.streamLocalSoon

Variant	Description
`Teleport`	Teleport the app.
`StreamRemote`	Stream the remote window here.
`StreamLocalSoon`	Streaming a local window is not built yet: an honest notice.

`AppPickerEvent` enum#

.loaded(entries: [AppCatalogEntry])
.failed(message: String, causeTexts: [String], causeInstalled: Bool)
.query(query: String)
.select(id: String)
.choose(id: String?)
.preselect(entry: AppCatalogEntry, files: [String])
.move(moves: AppTeleportMove)
.files(files: [String])
.removeFile(path: String)
.sensitive(group: AppSensitiveGroup, value: Bool)
.plan
.planned(plan: AppTeleportPlan)
.acknowledge(value: Bool)
.saveToKeyvault(value: Bool)
.acknowledgeRelayPlaintext(value: Bool)
.confirm
.progress(event: AppTeleportRunEvent)
.finished(report: AppTeleportRunReport)
.back

Variant	Description
`Loaded`	The catalog arrived. Fields: `entries: Vec<AppCatalogEntry>`
`Failed`	Something failed. Fields: `message: String`, `cause_texts: Vec<String>`, `cause_installed: bool`
`Query`	Search. Fields: `query: String`
`Select`	Highlight. Fields: `id: String`
`Choose`	Open the options for the highlighted (or given) app. Fields: `id: Option<String>`
`Preselect`	Start on an app (a drop or a window drag). Fields: `entry: AppCatalogEntry`, `files: Vec<String>`
`Move`	What moves. Fields: `moves: AppTeleportMove`
`Files`	Add files. Fields: `files: Vec<String>`
`RemoveFile`	Remove a file. Fields: `path: String`
`Sensitive`	An opt-in checkbox ("Keep me signed in", "Saved passwords", ...). Fields: `group: AppSensitiveGroup`, `value: bool`
`Plan`	Plan.
`Planned`	The plan arrived. Fields: `plan: AppTeleportPlan`
`Acknowledge`	The secrets checkbox. Fields: `value: bool`
`SaveToKeyvault`	The "Save to Keyvault" checkbox. Fields: `value: bool`
`AcknowledgeRelayPlaintext`	The relay-plaintext warning's checkbox (S1). Fields: `value: bool`
`Confirm`	Confirm the review.
`Progress`	A run event. Fields: `event: AppTeleportRunEvent`
`Finished`	The run finished. Fields: `report: AppTeleportRunReport`
`Back`	Back.

`AppPickerStep` enum#

.loading
.pick
.options
.planning
.consent
.running
.done
.error

Variant	Description
`Loading`	Loading the catalog.
`Pick`	Choosing an app.
`Options`	Choosing what moves.
`Planning`	Planning.
`Consent`	Reviewing the consent list.
`Running`	Running.
`Done`	Done.
`Error`	Failed.

`AppPickerTab` enum#

.space
.thisMac

Variant	Description
`Space`	This machine's windows, teleported into the Space.
`ThisMac`	The Space's windows, streamed here.

`AppTeleportCapability` enum#

.full
.installOnly
.unsupported

Variant	Description
`Full`	App and signed-in state.
`InstallOnly`	App, empty or with files.
`Unsupported`	Not available.

`AppTeleportMove` enum#

.appOnly
.appWithFiles
.appWithState

Variant	Description
`AppOnly`	Just the app.
`AppWithFiles`	The app with files or folders.
`AppWithState`	The app with its signed-in state.

`AppTeleportRunPhase` enum#

.started
.progress
.finished
.failed
.done

Variant	Description
`Started`	A step started.
`Progress`	Bytes moved.
`Finished`	A step finished.
`Failed`	A step failed.
`Done`	All done.

`AppTransferPhase` enum#

.active
.error

Variant	Description
`Active`	Uploading.
`Error`	Failed.

`AppTransferStatus` enum#

.start
.progress
.done
.error

Variant	Description
`Start`	Began (or retried).
`Progress`	Bytes moved.
`Done`	Finished.
`Error`	Failed.

`app_catalog_entries_from_json`#

Picker catalog entries from JSON (fixtures, parity flows).

func appCatalogEntriesFromJson(json: String) throws -> [AppCatalogEntry]

Parameter	Type	Default
`json`	`String`	required

Returns Vec<AppCatalogEntry> · Raises CuaError

`app_catalog_entry`#

A catalog row from Teleport.catalog, as the picker's entry.

func appCatalogEntry(entry: TeleportCatalogEntry) -> AppCatalogEntry

Parameter	Type	Default
`entry`	`TeleportCatalogEntry`	required

Returns AppCatalogEntry

`app_picker_can_plan`#

Planning is possible.

func appPickerCanPlan(state: AppPickerState) -> Bool

Parameter	Type	Default
`state`	`AppPickerState`	required

Returns bool

`app_picker_consent`#

The consent the confirmed review carries.

func appPickerConsent(state: AppPickerState) -> AppTeleportConsent

Parameter	Type	Default
`state`	`AppPickerState`	required

Returns AppTeleportConsent

`app_picker_initial`#

"Teleport an app..." first state.

func appPickerInitial(spaceName: String) -> AppPickerState

Parameter	Type	Default
`space_name`	`String`	required

Returns AppPickerState

`app_picker_plan_sensitive`#

The groups the plan asks for (TeleportPlanOptions.sensitive_groups).

func appPickerPlanSensitive(state: AppPickerState) -> [AppSensitiveGroup]

Parameter	Type	Default
`state`	`AppPickerState`	required

Returns Vec<AppSensitiveGroup>

`app_picker_primary`#

The primary button of the window picker.

func appPickerPrimary(tab: AppPickerTab, selectedSupported: Bool?) -> AppPickerPrimary

Parameter	Type	Default
`tab`	`AppPickerTab`	required
`selected_supported`	`Option<bool>`	required

Returns AppPickerPrimary

`app_picker_progress`#

Run progress in [0, 1].

func appPickerProgress(state: AppPickerState) -> Double

Parameter	Type	Default
`state`	`AppPickerState`	required

Returns f64

`app_picker_reduce`#

Advances the picker.

func appPickerReduce(state: AppPickerState, event: AppPickerEvent) -> AppPickerState

Parameter	Type	Default
`state`	`AppPickerState`	required
`event`	`AppPickerEvent`	required

Returns AppPickerState

`app_picker_review`#

The review screen, when a plan is under review.

func appPickerReview(state: AppPickerState) -> AppReviewView?

Parameter	Type	Default
`state`	`AppPickerState`	required

Returns Option<AppReviewView>

`app_picker_sections`#

The pick list's sections.

func appPickerSections(state: AppPickerState) -> [AppEntrySection]

Parameter	Type	Default
`state`	`AppPickerState`	required

Returns Vec<AppEntrySection>

`app_picker_sensitive_options`#

The options step's opt-in checkboxes ("Keep me signed in", "Saved passwords", "Browsing history"), with the signed-in state move chosen.

func appPickerSensitiveOptions(state: AppPickerState) -> [AppSensitiveOption]

Parameter	Type	Default
`state`	`AppPickerState`	required

Returns Vec<AppSensitiveOption>

`app_teleport_plan`#

A plan from Teleport.plan, as the review's plan.

func appTeleportPlan(plan: TeleportPlan) -> AppTeleportPlan

Parameter	Type	Default
`plan`	`TeleportPlan`	required

Returns AppTeleportPlan

`app_teleport_plan_from_json`#

A teleport plan from JSON (fixtures, parity flows).

func appTeleportPlanFromJson(json: String) throws -> AppTeleportPlan

Parameter	Type	Default
`json`	`String`	required

Returns AppTeleportPlan · Raises CuaError

`app_transfer_reduce`#

Advances the transfer overlay (None hides it).

func appTransferReduce(state: AppTransferOverlayState?, signal: AppTransferSignal) -> AppTransferOverlayState?

Parameter	Type	Default
`state`	`Option<AppTransferOverlayState>`	required
`signal`	`AppTransferSignal`	required

Returns Option<AppTransferOverlayState>

`app_transfer_title`#

The transfer overlay's title.

func appTransferTitle(state: AppTransferOverlayState) -> String

Parameter	Type	Default
`state`	`AppTransferOverlayState`	required

Returns String

Teleport picker

AppEntrySection record#

AppReviewView record#

AppPlanStepView record#

AppInstallCuaPrompt record#

AppCatalogEntry record#

AppConsentItem record#

AppDragOverlayState record#

AppDragOverlayTransition record#

AppPickerPrimary record#

AppPickerState record#

AppTeleportConsent record#

AppTeleportPlan record#

AppTeleportRunEvent record#

AppTeleportRunReport record#

AppTransferOverlayState record#

AppTransferSignal record#

AppConsentKind enum#

AppDragOverlayEffect enum#

AppDragOverlayEvent enum#

AppDragOverlayPhase enum#

AppPickerAction enum#

AppPickerEvent enum#

AppPickerStep enum#

AppPickerTab enum#

AppTeleportCapability enum#

AppTeleportMove enum#

AppTeleportRunPhase enum#

AppTransferPhase enum#

AppTransferStatus enum#

app_catalog_entries_from_json#

app_catalog_entry#

app_picker_can_plan#

app_picker_consent#

app_picker_initial#

app_picker_plan_sensitive#

app_picker_primary#

app_picker_progress#

app_picker_reduce#

app_picker_review#

app_picker_sections#

app_picker_sensitive_options#

app_teleport_plan#

app_teleport_plan_from_json#

app_transfer_reduce#

app_transfer_title#

AppEntrySection record#

AppReviewView record#

AppPlanStepView record#

AppInstallCuaPrompt record#

AppCatalogEntry record#

AppConsentItem record#

AppDragOverlayState record#

AppDragOverlayTransition record#

AppPickerPrimary record#

AppPickerState record#

AppTeleportConsent record#

AppTeleportPlan record#

AppTeleportRunEvent record#

AppTeleportRunReport record#

AppTransferOverlayState record#

AppTransferSignal record#

AppConsentKind enum#

AppDragOverlayEffect enum#

AppDragOverlayEvent enum#

AppDragOverlayPhase enum#

AppPickerAction enum#

AppPickerEvent enum#

AppPickerStep enum#

AppPickerTab enum#

AppTeleportCapability enum#

AppTeleportMove enum#

AppTeleportRunPhase enum#

AppTransferPhase enum#

AppTransferStatus enum#

app_catalog_entries_from_json#

app_catalog_entry#

app_picker_can_plan#

app_picker_consent#

app_picker_initial#

`AppEntrySection` record#

`AppReviewView` record#

`AppPlanStepView` record#

`AppInstallCuaPrompt` record#

`AppCatalogEntry` record#

`AppConsentItem` record#

`AppDragOverlayState` record#

`AppDragOverlayTransition` record#

`AppPickerPrimary` record#

`AppPickerState` record#

`AppTeleportConsent` record#

`AppTeleportPlan` record#

`AppTeleportRunEvent` record#

`AppTeleportRunReport` record#

`AppTransferOverlayState` record#

`AppTransferSignal` record#

`AppConsentKind` enum#

`AppDragOverlayEffect` enum#

`AppDragOverlayEvent` enum#

`AppDragOverlayPhase` enum#

`AppPickerAction` enum#

`AppPickerEvent` enum#

`AppPickerStep` enum#

`AppPickerTab` enum#

`AppTeleportCapability` enum#

`AppTeleportMove` enum#

`AppTeleportRunPhase` enum#

`AppTransferPhase` enum#

`AppTransferStatus` enum#

`app_catalog_entries_from_json`#

`app_catalog_entry`#

`app_picker_can_plan`#

`app_picker_consent`#

`app_picker_initial`#

`app_picker_plan_sensitive`#

`app_picker_primary`#

`app_picker_progress`#

`app_picker_reduce`#

`app_picker_review`#

`app_picker_sections`#

`app_picker_sensitive_options`#

`app_teleport_plan`#

`app_teleport_plan_from_json`#

`app_transfer_reduce`#

`app_transfer_title`#

`AppEntrySection` record#

`AppReviewView` record#

`AppPlanStepView` record#

`AppInstallCuaPrompt` record#

`AppCatalogEntry` record#

`AppConsentItem` record#

`AppDragOverlayState` record#

`AppDragOverlayTransition` record#

`AppPickerPrimary` record#

`AppPickerState` record#

`AppTeleportConsent` record#

`AppTeleportPlan` record#

`AppTeleportRunEvent` record#

`AppTeleportRunReport` record#

`AppTransferOverlayState` record#

`AppTransferSignal` record#

`AppConsentKind` enum#

`AppDragOverlayEffect` enum#

`AppDragOverlayEvent` enum#

`AppDragOverlayPhase` enum#

`AppPickerAction` enum#

`AppPickerEvent` enum#

`AppPickerStep` enum#

`AppPickerTab` enum#

`AppTeleportCapability` enum#

`AppTeleportMove` enum#

`AppTeleportRunPhase` enum#

`AppTransferPhase` enum#

`AppTransferStatus` enum#

`app_catalog_entries_from_json`#

`app_catalog_entry`#

`app_picker_can_plan`#

`app_picker_consent`#

`app_picker_initial`#

`app_picker_plan_sensitive`#