Getting started and the command palette
The getting-started checklist, the command palette's ranking and the shared keyboard shortcuts.
The getting-started checklist, the command palette's ranking and the shared keyboard shortcuts.
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 core functions beside the Spaces app core screens. The host app keeps the one AppChecklistState. app_checklist_observe_from reads what the app shows (the Machines page rows, the Spaces, the agents) as the same Observe action in every UI. app_checklist_reduce applies a checklist action (a step done, shown, closed, opened again, what the app shows now, or progress merged from another copy) and returns the new state with the usage events it means; app_checklist_view derives the rows, title and progress. app_palette_rank orders the command palette's entries for a query, and app_keybindings lists the default keyboard shortcuts the apps share.
AppChecklistRow record#| Field | Type | Default | Description |
|---|---|---|---|
step | AppChecklistStep | The step. | |
title | String | "Add a machine". | |
detail | String | One line under the title. | |
action | String | The button that does it; hidden once done. | |
done | bool | Done (ticked, struck through). |
AppChecklistSeen record#| Field | Type | Default | Description |
|---|---|---|---|
machines | Vec<AppMachinePageRow> | The Machines page's rows (crate.machines.page_rows). | |
spaces | Vec<AppSpace> | The Spaces list. | |
agents | u32 | Persistent agents listed. | |
runs | u32 | Agent runs listed in any Space. |
AppChecklistState record#Returned by app_checklist_state_from_json.
| Field | Type | Default | Description |
|---|---|---|---|
done | Vec<AppChecklistStep> | Steps done, each once, in checklist order. | |
dismissed | bool | Closed with ×; Getting Started opens it again. | |
shown | bool | It was on screen once (checklist_shown was recorded). |
AppChecklistTransition record#Returned by app_checklist_reduce.
| Field | Type | Default | Description |
|---|---|---|---|
state | AppChecklistState | The new state (save it when it changed). | |
signals | Vec<AppTelemetrySignal> | cua_onboarding_step events to record (checklist_<event>). |
AppChecklistView record#Returned by app_checklist_view.
| Field | Type | Default | Description |
|---|---|---|---|
visible | bool | On screen (not closed). | |
complete | bool | Every step done. | |
title | String | "Get started", or "You're set up" when complete. | |
detail | String | The line under the title. | |
progress | String | "2 of 5". | |
close_label / closeLabel | String | The close button's accessibility label. | |
rows | Vec<AppChecklistRow> | The steps in order. |
AppKeybinding record#Returned by app_keybindings.
| Field | Type | Default | Description |
|---|---|---|---|
command | String | commandPalette.toggle, nav.spaces, ... | |
key | String | mod+k, mod+shift+l: mod is ⌘ on macOS and Ctrl elsewhere. |
AppPaletteEntry record#| Field | Type | Default | Description |
|---|---|---|---|
group | String | "Actions", "Go to", "Spaces". | |
label | String | "New Space". | |
hint | Option<String> | Secondary text ("Linux"). | |
keywords | Option<String> | Extra words it answers to ("create add"). |
AppChecklistAction enum#.done(step: AppChecklistStep)
.shown
.dismiss
.reopen
.observe(otherMachine: Bool, hasSpace: Bool, agentRan: Bool)
.merge(state: AppChecklistState)| Variant | Description |
|---|---|
Done | A step finished (a teleport ran, a Space was shared). Fields: step: AppChecklistStep |
Shown | The checklist is on screen. |
Dismiss | Closed with ×. |
Reopen | Getting Started (the palette, the Help menu): open it again. |
Observe | What the app shows now: each true ticks its step off. Fields: other_machine: bool, has_space: bool, agent_ran: bool |
Merge | Progress kept elsewhere before (the web UI's own storage, another copy of the file): its steps are ticked, and it stays closed or shown if it was. Its events were recorded where it was ticked, so none are recorded again. Fields: state: AppChecklistState |
AppChecklistStep enum#.addMachine
.createSpace
.teleport
.share
.runAgent| Variant | Description |
|---|---|
AddMachine | Connect another computer you own. |
CreateSpace | Create a Space. |
Teleport | Teleport an app into a Space. |
Share | Share a Space with someone. |
RunAgent | Run an agent. |
app_checklist_observe_from#What the app shows as the checklist's Observe (every UI the same).
func appChecklistObserveFrom(seen: AppChecklistSeen) -> AppChecklistAction| Parameter | Type | Default |
|---|---|---|
seen | AppChecklistSeen | required |
Returns AppChecklistAction
app_checklist_reduce#The getting-started checklist after action, and its usage events.
func appChecklistReduce(state: AppChecklistState, action: AppChecklistAction) -> AppChecklistTransition| Parameter | Type | Default |
|---|---|---|
state | AppChecklistState | required |
action | AppChecklistAction | required |
Returns AppChecklistTransition
app_checklist_state_from_json#Checklist state from JSON, steps as words (fixtures, parity flows).
func appChecklistStateFromJson(json: String) throws -> AppChecklistState| Parameter | Type | Default |
|---|---|---|
json | String | required |
Returns AppChecklistState · Raises CuaError
app_checklist_view#The getting-started checklist as drawn.
func appChecklistView(state: AppChecklistState) -> AppChecklistView| Parameter | Type | Default |
|---|---|---|
state | AppChecklistState | required |
Returns AppChecklistView
app_keybindings#The default keyboard shortcuts (the shared UI's keybindings.json).
func appKeybindings() -> [AppKeybinding]Returns Vec<AppKeybinding>
app_palette_rank#The command palette's matches for query, best first, as indices into
entries.
func appPaletteRank(entries: [AppPaletteEntry], query: String) -> [UInt32]| Parameter | Type | Default |
|---|---|---|
entries | Vec<AppPaletteEntry> | required |
query | String | required |
Returns Vec<u32>