Notch

The notch switcher: state, events, layout on the screen and motion.

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 notch is the Space switcher at the top of the screen. app_notch_reduce applies an event; app_notch_layout, app_notch_radii and app_notch_motion place and animate it.

`AppScreenFacts` record#

Field	Type	Description
`frame`	`AppLogicalRect`	`NSScreen.frame`.
`visible_frame` / `visibleFrame`	`AppLogicalRect`	`NSScreen.visibleFrame`.
`safe_area_top` / `safeAreaTop`	`f64`	`safeAreaInsets.top` (0 without a notch).
`aux_left_width` / `auxLeftWidth`	`Option<f64>`	`auxiliaryTopLeftArea` width, when present.
`aux_right_width` / `auxRightWidth`	`Option<f64>`	`auxiliaryTopRightArea` width, when present.

`AppLogicalRect` record#

Field	Type	Default	Description
`x`	`f64`
`y`	`f64`
`width`	`f64`
`height`	`f64`

`app_presence_name`#

The name on this user's presence cursor: the account's name, else its email's local part, else its username, else this computer's account (full, then short name). Never empty, never an agent's or "You".

func appPresenceName(name: String?, email: String?, username: String?, osFullName: String?, osUser: String?) -> String

Parameter	Type	Default
`name`	`Option<String>`	required
`email`	`Option<String>`	required
`username`	`Option<String>`	required
`os_full_name`	`Option<String>`	required
`os_user`	`Option<String>`	required

Returns String

`app_presence_principal_id`#

The stable principal id this user joins presence as.

func appPresencePrincipalId(email: String?, subject: String?, username: String?, osUser: String?) -> String

Parameter	Type	Default
`email`	`Option<String>`	required
`subject`	`Option<String>`	required
`username`	`Option<String>`	required
`os_user`	`Option<String>`	required

Returns String

`app_os_icon_svg`#

An OS icon's artwork (a single-color 24 x 24 SVG), by the id a tile carries (os-ubuntu, ...).

func appOsIconSvg(id: String) -> String?

Parameter	Type	Default
`id`	`String`	required

Returns Option<String>

`app_os_icon_system_symbol`#

The system symbol drawn instead of the SVG on macOS (apple.logo).

func appOsIconSystemSymbol(id: String) -> String?

Parameter	Type	Default
`id`	`String`	required

Returns Option<String>

`AppNotchActivity` record#

Field	Type	Description
`kind`	`AppNotchActivityKind`	Which.
`label`	`String`	Spoken label and tooltip.
`symbol`	`Option<String>`	The symbol to draw (the hotspot), else a ring.
`permille`	`Option<u32>`	Real progress in thousandths (a transfer with a known total).
`started_at` / `startedAt`	`Option<i64>`	Epoch ms the ring's estimate runs from (the earliest starting Space); none means from when the ring appears.
`estimate_ms` / `estimateMs`	`u32`	The estimate reaches about 80% after this long (`estimated_progress`).

`AppNotchButton` record#

Field	Type	Description
`id`	`AppNotchButtonId`	What it does.
`symbol`	`String`	SF Symbol.
`label`	`String`	Accessibility label.
`help`	`String`	Tooltip.

`AppNotchHeader` record#

Field	Type	Description
`query`	`String`	The search text.
`placeholder`	`String`	"Search".
`search_label` / `searchLabel`	`String`	The field's spoken label.
`match_count` / `matchCount`	`Option<u32>`	How many Spaces match, while searching.
`buttons`	`Vec<AppNotchButton>`	Left to right: the list, then Settings at the far right.

`AppNotchLayout` record#

Returned by app_notch_layout.

Field	Type	Description
`has_notch` / `hasNotch`	`bool`	A real camera housing.
`notch`	`AppLogicalRect`	The notch (or the virtual one), AppKit coordinates.
`closed_frame` / `closedFrame`	`AppLogicalRect`	The closed panel's hit area: the notch grown for hover and drags.
`open_frame` / `openFrame`	`AppLogicalRect`	The open panel frame (tiles and prompt), top-centred.
`prompt_frame` / `promptFrame`	`AppLogicalRect`	The "Teleport to Cua" box alone, hanging below the notch.
`tab_frame` / `tabFrame`	`AppLogicalRect`	The "N Spaces" tab beside the closed notch (right of it), at its widest.
`tab_inset_notch` / `tabInsetNotch`	`f64`	Space between a closed tab's content (the "N Spaces" rows, the activity ring on the left) and the tab's edge toward the notch.
`tab_inset_outer` / `tabInsetOuter`	`f64`	Space between a closed tab's content and its outer edge (before the outer ear).
`stage_frame` / `stageFrame`	`AppLogicalRect`	The overlay window: every frame above plus `SHADOW_PADDING`, so the shape animates inside one window that never resizes mid-spring. Its transparent pixels pass clicks through.
`notch_style` / `notchStyle`	`bool`	Draw the black notch shape (true) or a floating glass capsule.

`AppNotchMotion` record#

Returned by app_notch_motion.

Field	Type	Description
`hover_dwell_ms` / `hoverDwellMs`	`u32`	Hover dwell before the panel opens.
`close_delay_ms` / `closeDelayMs`	`u32`	Delay before closing after the pointer leaves.
`open_response` / `openResponse`	`f64`	Opening spring response (s).
`open_damping` / `openDamping`	`f64`	Opening spring damping fraction.
`close_response` / `closeResponse`	`f64`	Closing spring response (s).
`close_damping` / `closeDamping`	`f64`	Closing spring damping fraction.
`reduced_duration` / `reducedDuration`	`f64`	Reduce Motion: opacity-only duration (s).
`hover_response` / `hoverResponse`	`f64`	Hover acknowledgement spring response (s): the closed notch grows a little while the dwell runs.
`hover_damping` / `hoverDamping`	`f64`	Hover acknowledgement damping fraction.
`hover_scale` / `hoverScale`	`f64`	Horizontal scale of the closed notch (and its tab) under the pointer.
`content_delay_ms` / `contentDelayMs`	`u32`	The content starts fading in this long after the shape starts opening (ms).
`content_in` / `contentIn`	`f64`	Content fade-in duration (s).
`content_out` / `contentOut`	`f64`	Content fade-out duration on close (s); the shape waits for it.
`content_scale` / `contentScale`	`f64`	Content scale at the start of its fade-in (anchored at the top).

`AppNotchPermission` record#

Field	Type	Description
`text`	`String`	The line.
`action`	`String`	The button.
`pane`	`String`	Which settings pane the button opens (`accessibility`).

`AppNotchPreview` record#

Field	Type	Description
`closed`	`AppLogicalRect`	The closed notch with its ears, top centred.
`open`	`AppLogicalRect`	The open panel, top centred.
`closed_radii` / `closedRadii`	`AppNotchRadii`	Closed radii, scaled.
`open_radii` / `openRadii`	`AppNotchRadii`	Open radii, scaled.
`tab`	`AppLogicalRect`	The "N Spaces" tab right of the notch.
`notch`	`AppLogicalRect`	The camera housing (the closed notch without its ears).
`view`	`AppNotchView`	The open panel's content at real size (the header row flanking the notch, then the tiles): the shells lay it out at `content_width` by `content_height` points and scale it by `scale` into `open`.
`content_width` / `contentWidth`	`f64`	The content's real width.
`content_height` / `contentHeight`	`f64`	The content's real height.
`notch_height` / `notchHeight`	`f64`	The real notch's height (the header row's height, real points).
`side`	`f64`	The content's side inset, real points (open top radius + padding).
`scale`	`f64`	Real points to stage points.

`AppNotchRadii` record#

Returned by app_notch_radii.

Field	Type	Default	Description
`top`	`f64`		Top (concave ear) radius.
`bottom`	`f64`		Bottom radius.

`AppNotchState` record#

Returned by app_notch_initial.

Field	Type	Description
`open`	`bool`	Opened by hover or click.
`hovering`	`bool`	The pointer is over the panel.
`drop_targeted` / `dropTargeted`	`bool`	A file or app drag (pasteboard) is over the panel.
`drag`	`AppDragOverlayState`	The window drag state machine.
`drag_permission_missing` / `dragPermissionMissing`	`bool`	Window-drag detection needs a permission this process lacks (macOS Accessibility): the open panel says so instead of failing silently.
`query`	`String`	The header's search text (cleared when the panel closes).
`hotspot`	`bool`	This machine shares its network to a Space (the hotspot).
`transfer`	`Option<AppNotchTransfer>`	A teleport or file transfer is in flight.
`keyvault`	`Option<String>`	Keyvault sign-ins are live in a Space right now (the core's `crate.keyvault.view.sharing_label`), so access is never silent.
`hidden`	`bool`	"Spaces tab in the notch: Hide" (menu bar only): nothing shows in the notch, and hover, clicks and window drags do nothing.

`AppNotchTab` record#

Field	Type	Default	Description
`count`	`String`		"9".
`word`	`String`		"Spaces" (or "Space").

`AppNotchTile` record#

Field	Type	Description
`id`	`String`	Space id.
`name`	`String`	Name.
`os`	`AppSpaceOs`	OS.
`status`	`AppSpaceStatus`	Status.
`dim`	`bool`	Drawn at reduced opacity.
`drop_target` / `dropTarget`	`bool`	Accepts a teleport drop (reachable).
`targeted`	`bool`	Under the dragged window.
`symbol`	`String`	The Space's OS icon id (`os_icon`: `os-macos`, `os-windows`, `os-ubuntu`, ..., `os-linux`); the artwork is `os_icon_svg`, or on macOS the system symbol `os_icon_system_symbol` names.
`label`	`String`	Accessibility label: name, OS and status.
`progress`	`Option<u32>`	While it is being created: overall progress in thousandths (a ring over the tile).
`progress_label` / `progressLabel`	`Option<String>`	While it is being created: the phase in words ("Starting…"), or "Failed"; while it is being deleted, "Deleting…".

`AppNotchTransfer` record#

Field	Type	Default	Description
`sent`	`Option<u64>`		Bytes sent so far.
`total`	`Option<u64>`		Total bytes, when known.

`AppNotchTransition` record#

Returned by app_notch_reduce.

Field	Type	Default	Description
`state`	`AppNotchState`		New state.
`effects`	`Vec<AppNotchEffect>`		Effects to run.

`AppNotchView` record#

Returned by app_notch_view.

Field	Type	Description
`phase`	`AppNotchPhase`	What shows.
`tiles`	`Vec<AppNotchTile>`	The tiles (in `tiles`).
`drop_mode` / `dropMode`	`bool`	Tiles accept drops.
`prompt`	`Option<String>`	The prompt line.
`label`	`String`	Accessibility label of the panel.
`count_label` / `countLabel`	`String`	"N Spaces": the tab's spoken label (remote Spaces only).
`tab`	`AppNotchTab`	The tab's two rows: the count over the word.
`header`	`Option<AppNotchHeader>`	The row flanking the notch in the open panel: the search left of it, the buttons right of it. None while dropping.
`empty`	`Option<String>`	The line in place of the tiles when the search matches nothing.
`activity`	`Option<AppNotchActivity>`	The indicator left of the closed notch.
`hidden`	`bool`	The notch is hidden (menu bar only): draw nothing.
`show_tab` / `showTab`	`bool`	The tab shows (closed, no drag in flight; a drag tucks it away).
`hover_cue` / `hoverCue`	`bool`	The pointer rests on the closed notch while the dwell runs: the shells grow it by `NotchMotion.hover_scale`.
`permission`	`Option<AppNotchPermission>`	One line in the open panel when window drags cannot be detected.

`AppNotchActivityKind` enum#

.transfer
.remoteAccess
.hotspot
.provisioning
.deleting
.keyvault

Variant	Description
`Transfer`	A teleport or file transfer: a progress ring.
`RemoteAccess`	Someone is connected to this machine (host sharing): its symbol, pulsing, for as long as they are.
`Hotspot`	The network hotspot: its symbol, pulsing.
`Provisioning`	A Space starting: a progress ring on the startup estimate.
`Deleting`	A Space being deleted: a ring on the delete estimate.
`Keyvault`	Keyvault sign-ins live in a Space: the key symbol, pulsing.

`AppNotchButtonId` enum#

.list
.settings

Variant	Description
`List`	Opens the main window (the Spaces list).
`Settings`	Opens Settings.

`AppNotchEffect` enum#

.startDwell(ms: UInt32)
.startClose(ms: UInt32)
.cancelTimers
.drag(effect: AppDragOverlayEffect)

Variant	Description
`StartDwell`	Start (or restart) the dwell timer. Fields: `ms: u32`
`StartClose`	Start the close timer. Fields: `ms: u32`
`CancelTimers`	Cancel pending timers.
`Drag`	A window drag effect (capture the ghost, commit the teleport). Fields: `effect: AppDragOverlayEffect`

`AppNotchEvent` enum#

.hoverEnter
.hoverExit
.dwellElapsed
.closeElapsed
.click
.dismiss
.dropTargeted(targeted: Bool)
.drag(event: AppDragOverlayEvent)
.dragPermission(granted: Bool)
.search(query: String)
.escape
.visibility(shown: Bool)
.activity(hotspot: Bool, transfer: AppNotchTransfer?)
.keyvault(label: String?)

Variant	Description
`HoverEnter`	Pointer entered.
`HoverExit`	Pointer left.
`DwellElapsed`	The dwell timer the core asked for fired.
`CloseElapsed`	The close timer the core asked for fired.
`Click`	Click on the closed notch.
`Dismiss`	Esc or a click outside.
`DropTargeted`	A pasteboard drag entered (true) or left (false) the panel. Fields: `targeted: bool`
`Drag`	A window drag event. Fields: `event: AppDragOverlayEvent`
`DragPermission`	The shell checked the window-drag permission. Fields: `granted: bool`
`Search`	The header's search text changed. Fields: `query: String`
`Escape`	Esc: clears the search first, then closes.
`Visibility`	The notch setting changed: shown, or hidden (menu bar only). Fields: `shown: bool`
`Activity`	The hotspot or a transfer started, progressed or ended. Fields: `hotspot: bool`, `transfer: Option<AppNotchTransfer>`
`Keyvault`	Keyvault sharing started, changed or stopped (none: nothing live). Fields: `label: Option<String>`

`AppNotchPhase` enum#

.closed
.tiles
.prompt

Variant	Description
`Closed`	Just the notch.
`Tiles`	The Space tiles.
`Prompt`	The Teleport prompt ("Teleport to Cua").

`app_notch_estimated_progress`#

The activity ring's fill without real progress, in thousandths.

func appNotchEstimatedProgress(elapsedMs: Int64, estimateMs: UInt32) -> UInt32

Parameter	Type	Default
`elapsed_ms`	`i64`	required
`estimate_ms`	`u32`	required

Returns u32

`app_notch_initial`#

The notch panel's first state.

func appNotchInitial() -> AppNotchState

Returns AppNotchState

`app_notch_layout`#

The notch rectangle and panel frames for a screen.

func appNotchLayout(screen: AppScreenFacts, prompt: Bool) -> AppNotchLayout

Parameter	Type	Default
`screen`	`AppScreenFacts`	required
`prompt`	`bool`	required

Returns AppNotchLayout

`app_notch_motion`#

The springs and delays every shell animates with.

func appNotchMotion() -> AppNotchMotion

Returns AppNotchMotion

`app_notch_radii`#

Closed and open corner radii.

func appNotchRadii() -> [AppNotchRadii]

Returns Vec<AppNotchRadii>

`app_notch_reduce`#

Advances the notch panel.

func appNotchReduce(state: AppNotchState, event: AppNotchEvent) -> AppNotchTransition

Parameter	Type	Default
`state`	`AppNotchState`	required
`event`	`AppNotchEvent`	required

Returns AppNotchTransition

`app_notch_tile_at`#

The drop-target tile under a point (AppKit coordinates) in the open panel; row when the line above the tiles shows.

func appNotchTileAt(layout: AppNotchLayout, tiles: [AppNotchTile], row: Bool, x: Double, y: Double) -> String?

Parameter	Type	Default
`layout`	`AppNotchLayout`	required
`tiles`	`Vec<AppNotchTile>`	required
`row`	`bool`	required
`x`	`f64`	required
`y`	`f64`	required

Returns Option<String>

`app_notch_view`#

The notch panel as drawn.

func appNotchView(state: AppNotchState, spaces: [AppSpace]) -> AppNotchView

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

Returns AppNotchView

Notch

AppScreenFacts record#

AppLogicalRect record#

app_presence_name#

app_presence_principal_id#

app_os_icon_svg#

app_os_icon_system_symbol#

AppNotchActivity record#

AppNotchButton record#

AppNotchHeader record#

AppNotchLayout record#

AppNotchMotion record#

AppNotchPermission record#

AppNotchPreview record#

AppNotchRadii record#

AppNotchState record#

AppNotchTab record#

AppNotchTile record#

AppNotchTransfer record#

AppNotchTransition record#

AppNotchView record#

AppNotchActivityKind enum#

AppNotchButtonId enum#

AppNotchEffect enum#

AppNotchEvent enum#

AppNotchPhase enum#

app_notch_estimated_progress#

app_notch_initial#

app_notch_layout#

app_notch_motion#

app_notch_radii#

app_notch_reduce#

app_notch_tile_at#

app_notch_view#

AppScreenFacts record#

AppLogicalRect record#

app_presence_name#

app_presence_principal_id#

app_os_icon_svg#

app_os_icon_system_symbol#

AppNotchActivity record#

AppNotchButton record#

AppNotchHeader record#

AppNotchLayout record#

AppNotchMotion record#

AppNotchPermission record#

AppNotchPreview record#

AppNotchRadii record#

AppNotchState record#

AppNotchTab record#

AppNotchTile record#

AppNotchTransfer record#

AppNotchTransition record#

AppNotchView record#

AppNotchActivityKind enum#

AppNotchButtonId enum#

AppNotchEffect enum#

AppNotchEvent enum#

AppNotchPhase enum#

app_notch_estimated_progress#

app_notch_initial#

app_notch_layout#

app_notch_motion#

app_notch_radii#

app_notch_reduce#

app_notch_tile_at#

app_notch_view#

`AppScreenFacts` record#

`AppLogicalRect` record#

`app_presence_name`#

`app_presence_principal_id`#

`app_os_icon_svg`#

`app_os_icon_system_symbol`#

`AppNotchActivity` record#

`AppNotchButton` record#

`AppNotchHeader` record#

`AppNotchLayout` record#

`AppNotchMotion` record#

`AppNotchPermission` record#

`AppNotchPreview` record#

`AppNotchRadii` record#

`AppNotchState` record#

`AppNotchTab` record#

`AppNotchTile` record#

`AppNotchTransfer` record#

`AppNotchTransition` record#

`AppNotchView` record#

`AppNotchActivityKind` enum#

`AppNotchButtonId` enum#

`AppNotchEffect` enum#

`AppNotchEvent` enum#

`AppNotchPhase` enum#

`app_notch_estimated_progress`#

`app_notch_initial`#

`app_notch_layout`#

`app_notch_motion`#

`app_notch_radii`#

`app_notch_reduce`#

`app_notch_tile_at`#

`app_notch_view`#

`AppScreenFacts` record#

`AppLogicalRect` record#

`app_presence_name`#

`app_presence_principal_id`#

`app_os_icon_svg`#

`app_os_icon_system_symbol`#

`AppNotchActivity` record#

`AppNotchButton` record#

`AppNotchHeader` record#

`AppNotchLayout` record#

`AppNotchMotion` record#

`AppNotchPermission` record#

`AppNotchPreview` record#

`AppNotchRadii` record#

`AppNotchState` record#

`AppNotchTab` record#

`AppNotchTile` record#

`AppNotchTransfer` record#

`AppNotchTransition` record#

`AppNotchView` record#

`AppNotchActivityKind` enum#

`AppNotchButtonId` enum#

`AppNotchEffect` enum#

`AppNotchEvent` enum#

`AppNotchPhase` enum#

`app_notch_estimated_progress`#

`app_notch_initial`#

`app_notch_layout`#

`app_notch_motion`#

`app_notch_radii`#

`app_notch_reduce`#

`app_notch_tile_at`#

`app_notch_view`#