Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

feat(spaces): register the ⌘⇧Space global shortcut on macOS (CUA-1415) (#5026)

Francesco Bonacci41047e23d469
diff --git a/apps/cua-spaces-desktop/src/bridge/settings.ts b/apps/cua-spaces-desktop/src/bridge/settings.ts
index eb9d81f9a1..fa89989494 100644
--- a/apps/cua-spaces-desktop/src/bridge/settings.ts
+++ b/apps/cua-spaces-desktop/src/bridge/settings.ts
@@ -77,12 +77,14 @@ export function experimentsPage(model: AppModel) {
return { ...page, sections: page.sections.map((s) => ({ ...s, rows: s.rows.filter((r) => !WEB_UI_ROWS.has(r.id)) })) };
}
-/** `settings.get`'s answer: General, Experiments and the update channel (null: no updater). */
+/** `settings.get`'s answer: General, Experiments, the update channel (null:
+ * no updater) and the global shortcut (null: none here). */
export function settingsState(model: AppModel, parts: HostParts) {
return {
page: encode(settingsPage(model, parts)),
experiments: encode(experimentsPage(model)),
updateChannel: parts.updates.updater === null ? null : parts.updates.channelWord,
+ globalShortcut: parts.system?.globalShortcut?.() ?? null,
};
}
diff --git a/apps/cua-spaces-desktop/src/bridge/system.ts b/apps/cua-spaces-desktop/src/bridge/system.ts
index 25820d0825..1e620d9f90 100644
--- a/apps/cua-spaces-desktop/src/bridge/system.ts
+++ b/apps/cua-spaces-desktop/src/bridge/system.ts
@@ -35,4 +35,7 @@ export interface SystemServices {
updater: UpdaterDriving | null;
/** The user's home folder, as the daemon sees it. */
home: string;
+ /** The global shortcut (macOS), registered again if the system refused it
+ * before; absent or null where the shell has none. */
+ globalShortcut?: () => { label: string; registered: boolean } | null;
}
diff --git a/apps/cua-spaces-desktop/src/global-shortcut.ts b/apps/cua-spaces-desktop/src/global-shortcut.ts
new file mode 100644
index 0000000000..3e96f69a81
--- /dev/null
+++ b/apps/cua-spaces-desktop/src/global-shortcut.ts
@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: FSL-1.1-MIT
+// Copyright (c) 2026 Cua AI, Inc.
+
+// The global shortcut (macOS, as the SwiftUI app's): ⌘⇧Space brings the
+// main window to the front from any app, through Electron's globalShortcut.
+// Another app may already hold the keys; then the registration fails, and
+// Settings says so and tries again each time it opens (`ensure`).
+import { app, globalShortcut } from "electron";
+
+export const GLOBAL_SHORTCUT = { label: "⌘⇧Space", accelerator: "Command+Shift+Space" } as const;
+
+export interface GlobalShortcutState {
+ label: string;
+ registered: boolean;
+}
+
+export class GlobalShortcut {
+ private registered = false;
+
+ constructor(
+ private readonly onPress: () => void,
+ private readonly register: (accelerator: string, callback: () => void) => boolean = (a, cb) => globalShortcut.register(a, cb),
+ ) {}
+
+ /** Registers the keys unless they already are; what the system answered. */
+ ensure(): GlobalShortcutState {
+ if (!this.registered) this.registered = this.register(GLOBAL_SHORTCUT.accelerator, this.onPress);
+ return { label: GLOBAL_SHORTCUT.label, registered: this.registered };
+ }
+}
+
+/** The shortcut on macOS (the Windows and Linux shells have none), registered
+ * once the app is ready and released when it quits. */
+export function installGlobalShortcut(platform: NodeJS.Platform, onPress: () => void): GlobalShortcut | null {
+ if (platform !== "darwin") return null;
+ const shortcut = new GlobalShortcut(onPress);
+ shortcut.ensure();
+ app.on("will-quit", () => globalShortcut.unregisterAll());
+ return shortcut;
+}
diff --git a/apps/cua-spaces-desktop/src/main.ts b/apps/cua-spaces-desktop/src/main.ts
index 43566f2041..ef564c6bfe 100644
--- a/apps/cua-spaces-desktop/src/main.ts
+++ b/apps/cua-spaces-desktop/src/main.ts
@@ -10,6 +10,7 @@ import { createBridge } from "./bridge";
import { hasBrowser } from "./browser";
import { appBuild } from "./bundle-version";
import { ELECTRON_EVENT_CHANNEL } from "./channels";
+import { installGlobalShortcut, type GlobalShortcut } from "./global-shortcut";
import { applyVideoDecodeSwitches } from "./gpu";
import { menuItems, realSpaces, startHost } from "./bridge/host-start";
import { installBridgeIpc } from "./bridge/ipc";
@@ -86,7 +87,7 @@ function migrateSwiftApp() {
}
/** The native host: the library, the model on it and the bridge. */
-async function startNativeHost(showRoute: (route: string) => void) {
+async function startNativeHost(showRoute: (route: string) => void, globalShortcut: GlobalShortcut | null) {
const dir = nativeDir({
platform: process.platform,
arch: process.arch,
@@ -124,7 +125,7 @@ async function startNativeHost(showRoute: (route: string) => void) {
build,
platform: process.platform,
env: process.env,
- system: makeSystem({ native, showRoute }),
+ system: makeSystem({ native, showRoute, globalShortcut }),
ui: {
openSpace: (spaceId, name, os) => void viewers.open(spaceId, name, os),
setBackground: (win, color, appearance) => {
@@ -250,10 +251,17 @@ if (!app.requestSingleInstanceLock()) {
const { webRoot } = handleAppProtocol();
if (process.env.CUA_SPACES_LOG_STARTUP) console.log(`[cua-spaces] serving ${webRoot}`);
+ // ⌘⇧Space from any app: the main window, in front (never under the e2e switch).
+ const shortcut = E2E_DEMO
+ ? null
+ : installGlobalShortcut(process.platform, () => {
+ app.focus({ steal: true });
+ showMain();
+ });
let host: Awaited<ReturnType<typeof startNativeHost>> | null = null;
if (!E2E_DEMO) {
try {
- host = await startNativeHost(showRoute);
+ host = await startNativeHost(showRoute, shortcut);
} catch (error) {
// A broken install: say so plainly, never show the app without its data.
const why = error instanceof Error ? error.message : String(error);
diff --git a/apps/cua-spaces-desktop/src/system.ts b/apps/cua-spaces-desktop/src/system.ts
index 5f8b04eb39..e155ded336 100644
--- a/apps/cua-spaces-desktop/src/system.ts
+++ b/apps/cua-spaces-desktop/src/system.ts
@@ -4,7 +4,7 @@
// The bridge's system services with Electron (`bridge/system.ts`): links and
// settings panes, Show in Finder / Explorer, notifications (a click brings
// the app to the page it is about), the owner check before approving a
-// device, the login item and the updater.
+// device, the login item, the updater and the global shortcut's state.
//
// The owner check is the system's prompt through the app core
// (`model/presence.ts`: Touch ID, Windows Hello, polkit), with a dialog of
@@ -12,6 +12,7 @@
import { app, BrowserWindow, dialog, Notification, shell } from "electron";
import * as os from "node:os";
import type { SystemNote, SystemServices } from "./bridge/system";
+import type { GlobalShortcut } from "./global-shortcut";
import { confirmOwner } from "./model/presence";
import { makeLoginItem } from "./login-item";
import type { Native } from "./native/load";
@@ -19,7 +20,12 @@ import { ElectronUpdater } from "./updater";
const OPENABLE = /^(https?:|x-apple\.systempreferences:|ms-settings:)/;
-export function makeSystem(o: { native: Native; showRoute: (route: string) => void; platform?: NodeJS.Platform }): SystemServices {
+export function makeSystem(o: {
+ native: Native;
+ showRoute: (route: string) => void;
+ globalShortcut?: GlobalShortcut | null;
+ platform?: NodeJS.Platform;
+}): SystemServices {
const platform = o.platform ?? process.platform;
// Shown notifications, by id (a newer one with the same id replaces it).
const shown = new Map<string, Notification>();
@@ -61,5 +67,6 @@ export function makeSystem(o: { native: Native; showRoute: (route: string) => vo
loginItem: makeLoginItem(platform),
updater: ElectronUpdater.start(),
home: process.env.HOME || os.homedir(),
+ globalShortcut: () => o.globalShortcut?.ensure() ?? null,
};
}
diff --git a/apps/cua-spaces-desktop/test/global-shortcut.test.ts b/apps/cua-spaces-desktop/test/global-shortcut.test.ts
new file mode 100644
index 0000000000..b81db04d10
--- /dev/null
+++ b/apps/cua-spaces-desktop/test/global-shortcut.test.ts
@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: FSL-1.1-MIT
+// Copyright (c) 2026 Cua AI, Inc.
+
+// The global shortcut: registered on macOS only, and when another app holds
+// the keys, refused (Settings says so) and tried again on the next read.
+import { describe, expect, it, vi } from "vitest";
+
+const register = vi.fn(() => true);
+const on = vi.fn();
+vi.mock("electron", () => ({ app: { on }, globalShortcut: { register, unregisterAll: vi.fn() } }));
+const { GlobalShortcut, installGlobalShortcut } = await import("../src/global-shortcut");
+
+describe("the global shortcut", () => {
+ it("is the Mac's only", () => {
+ expect(installGlobalShortcut("win32", () => {})).toBeNull();
+ expect(installGlobalShortcut("linux", () => {})).toBeNull();
+ expect(register).not.toHaveBeenCalled();
+ const shortcut = installGlobalShortcut("darwin", () => {});
+ expect(register).toHaveBeenCalledWith("Command+Shift+Space", expect.any(Function));
+ expect(shortcut?.ensure()).toEqual({ label: "⌘⇧Space", registered: true });
+ // Once registered, never again; released when the app quits.
+ expect(register).toHaveBeenCalledTimes(1);
+ expect(on).toHaveBeenCalledWith("will-quit", expect.any(Function));
+ });
+
+ it("says when another app holds the keys, and tries again on the next read", () => {
+ const answers = [false, false, true];
+ const tries = vi.fn(() => answers.shift() ?? true);
+ const pressed = vi.fn();
+ let callback = () => {};
+ const shortcut = new GlobalShortcut(pressed, (_, cb) => {
+ callback = cb;
+ return tries();
+ });
+ expect(shortcut.ensure().registered).toBe(false);
+ expect(shortcut.ensure().registered).toBe(false);
+ expect(shortcut.ensure().registered).toBe(true);
+ expect(shortcut.ensure().registered).toBe(true);
+ expect(tries).toHaveBeenCalledTimes(3);
+ callback();
+ expect(pressed).toHaveBeenCalledOnce();
+ });
+});
diff --git a/apps/cua-spaces-desktop/test/host-bridge.test.ts b/apps/cua-spaces-desktop/test/host-bridge.test.ts
index 8df5186030..83c4fd182f 100644
--- a/apps/cua-spaces-desktop/test/host-bridge.test.ts
+++ b/apps/cua-spaces-desktop/test/host-bridge.test.ts
@@ -477,11 +477,17 @@ describe.skipIf(!built)("This machine, Devices and Settings on the app core", ()
// MARK: Settings
it("lays out General with the Teams waitlist, Welcome and What is collected, and the runtimes", async () => {
- const s = (await call("settings.get")) as { page: { sections: { id: string; rows: { id: string }[] }[] }; updateChannel: unknown };
+ const s = (await call("settings.get")) as {
+ page: { sections: { id: string; rows: { id: string }[] }[] };
+ updateChannel: unknown;
+ globalShortcut: unknown;
+ };
const rows = s.page.sections.flatMap((x) => x.rows.map((r) => r.id));
expect(rows).toEqual(expect.arrayContaining(["account", "notch", "auto-connect", "welcome", "teams", "telemetry", "telemetry-note", "launch-at-login"]));
expect(rows).toEqual(expect.arrayContaining(["macos-runtime", "linux-runtime"]));
expect(s.updateChannel).toBe("stable");
+ // Another app holds ⌘⇧Space: the page says so.
+ expect(s.globalShortcut).toEqual({ label: "\u2318\u21e7Space", registered: false });
});
it("chooses each row as the Swift app does", async () => {
diff --git a/apps/cua-spaces-desktop/test/host-fixtures.ts b/apps/cua-spaces-desktop/test/host-fixtures.ts
index cc50382df3..8b7f024b7d 100644
--- a/apps/cua-spaces-desktop/test/host-fixtures.ts
+++ b/apps/cua-spaces-desktop/test/host-fixtures.ts
@@ -279,7 +279,11 @@ export class FixtureSystem implements SystemServices {
allow = true;
loginItem = new FixtureLoginItem();
updater = new FixtureUpdater(Date.UTC(2026, 9, 7, 12, 0));
+ shortcut: { label: string; registered: boolean } | null = { label: "\u2318\u21e7Space", registered: false };
constructor(readonly home: string) {}
+ globalShortcut() {
+ return this.shortcut;
+ }
async openExternal(url: string) {
this.opened.push(url);
}
diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/GlobalShortcut.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/GlobalShortcut.swift
new file mode 100644
index 0000000000..02548a5e88
--- /dev/null
+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Models/GlobalShortcut.swift
@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: FSL-1.1-MIT
+// Copyright (c) 2026 Cua AI, Inc.
+
+import AppKit
+import Carbon.HIToolbox
+
+/// ⌘⇧Space from any app brings Cua Spaces to the front: the main window,
+/// or the New UI window while that is the one in use. Another app may hold
+/// the keys; then the system refuses them, Settings says so, and each read
+/// of Settings tries again (`ensure`).
+@MainActor
+final class GlobalShortcut {
+ static let label = "\u{2318}\u{21e7}Space"
+
+ /// The app's one shortcut, once `AppDelegate.start` registered it.
+ static var installed: GlobalShortcut?
+
+ private let tryRegister: () -> Bool
+ private(set) var registered = false
+
+ init(tryRegister: @escaping () -> Bool) {
+ self.tryRegister = tryRegister
+ }
+
+ /// Registers the keys unless they already are; whether the system gave them.
+ @discardableResult
+ func ensure() -> Bool {
+ if !registered { registered = tryRegister() }
+ return registered
+ }
+
+ /// `settings.get`'s `globalShortcut`.
+ var bridgeValue: [String: Any] { ["label": Self.label, "registered": ensure()] }
+
+ /// Registered now, pressing it brings the app to the front.
+ static func install(_ model: AppModel) {
+ let hotKey = CarbonHotKey(keyCode: UInt32(kVK_Space), modifiers: UInt32(cmdKey | shiftKey)) {
+ bringForward(model)
+ }
+ let shortcut = GlobalShortcut(tryRegister: hotKey.register)
+ shortcut.ensure()
+ installed = shortcut
+ }
+
+ /// The window of the UI in use, in front.
+ static func bringForward(_ model: AppModel) {
+ NSApp.activate()
+ if CuaSpacesMacApp.opensWebUIAtLaunch(model) {
+ WebUIWindowController.show(model: model)
+ } else {
+ WebUIWindowController.actions?.openMain()
+ }
+ }
+}
+
+/// A system-wide hot key through Carbon's `RegisterEventHotKey`, which needs
+/// no Accessibility permission and never sees other keystrokes. Exclusive:
+/// it fails when another app registered the same keys.
+@MainActor
+final class CarbonHotKey {
+ nonisolated static let signature: OSType = 0x4355_4153 // 'CUAS'
+ private let keyCode: UInt32
+ private let modifiers: UInt32
+ private let onPress: () -> Void
+ private var handler: EventHandlerRef?
+ private var ref: EventHotKeyRef?
+
+ init(keyCode: UInt32, modifiers: UInt32, onPress: @escaping () -> Void) {
+ self.keyCode = keyCode
+ self.modifiers = modifiers
+ self.onPress = onPress
+ }
+
+ func register() -> Bool {
+ if ref != nil { return true }
+ if handler == nil {
+ var type = EventTypeSpec(eventClass: OSType(kEventClassKeyboard), eventKind: UInt32(kEventHotKeyPressed))
+ let status = InstallEventHandler(GetApplicationEventTarget(), { _, event, data -> OSStatus in
+ var id = EventHotKeyID()
+ GetEventParameter(event, EventParamName(kEventParamDirectObject), EventParamType(typeEventHotKeyID),
+ nil, MemoryLayout<EventHotKeyID>.size, nil, &id)
+ guard let data, id.signature == CarbonHotKey.signature else { return OSStatus(eventNotHandledErr) }
+ let hotKey = Unmanaged<CarbonHotKey>.fromOpaque(data).takeUnretainedValue()
+ DispatchQueue.main.async { MainActor.assumeIsolated { hotKey.onPress() } }
+ return noErr
+ }, 1, &type, Unmanaged.passUnretained(self).toOpaque(), &handler)
+ guard status == noErr else { return false }
+ }
+ let id = EventHotKeyID(signature: Self.signature, id: 1)
+ return RegisterEventHotKey(keyCode, modifiers, id, GetApplicationEventTarget(),
+ OptionBits(kEventHotKeyExclusive), &ref) == noErr
+ }
+}
diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/CuaSpacesMacApp.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/CuaSpacesMacApp.swift
index 7923567122..4ff6caf716 100644
--- a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/CuaSpacesMacApp.swift
+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/Views/CuaSpacesMacApp.swift
@@ -309,6 +309,8 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
teleport.prefetch()
}
notch = controller
+ // ⌘⇧Space from any app: the window of the UI in use, in front.
+ GlobalShortcut.install(model)
AppEnvironment.applyStartView(model, notch: controller)
// New UI on: its window is the one a launch opens (the main window
// is suppressed); not when opened at login.
diff --git a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/WebUIBridge.swift b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/WebUIBridge.swift
index b01a047ac4..7584c7abd3 100644
--- a/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/WebUIBridge.swift
+++ b/apps/cua-spaces-macos/Sources/CuaSpacesMacKit/WebHost/WebUIBridge.swift
@@ -437,6 +437,8 @@ final class WebUIBridge: NSObject, WKScriptMessageHandlerWithReply {
"experiments": BridgeValue.encode(model.experimentsPage),
// Settings → About's channel; null while this build has no updater.
"updateChannel": model.updates.updater == nil ? NSNull() : (model.updates.channel == .beta ? "beta" : "stable"),
+ // ⌘⇧Space, and whether the system gave it (tried again on each read).
+ "globalShortcut": GlobalShortcut.installed?.bridgeValue ?? NSNull(),
]
}
diff --git a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/WebUIHostTests.swift b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/WebUIHostTests.swift
index 9fdb2d3dfa..ac0adfd2e2 100644
--- a/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/WebUIHostTests.swift
+++ b/apps/cua-spaces-macos/Tests/CuaSpacesMacTests/WebUIHostTests.swift
@@ -269,6 +269,24 @@ struct WebUIHostTests {
#expect(model.updates.channel == .beta)
}
+ @Test func theGlobalShortcutSaysWhetherTheSystemGaveIt() async throws {
+ let (bridge, _) = bridge()
+ defer { GlobalShortcut.installed = nil }
+ GlobalShortcut.installed = nil
+ #expect((try await bridge.handle("settings.get", [:]) as? [String: Any])?["globalShortcut"] is NSNull)
+ // Another app holds the keys at launch, then lets them go: each read tries again.
+ var answers = [false, true]
+ var tries = 0
+ GlobalShortcut.installed = GlobalShortcut { tries += 1; return answers.removeFirst() }
+ GlobalShortcut.installed?.ensure()
+ let refused = (try await bridge.handle("settings.get", [:]) as? [String: Any])?["globalShortcut"] as? [String: Any]
+ #expect(refused?["label"] as? String == "\u{2318}\u{21e7}Space")
+ #expect(refused?["registered"] as? Bool == true)
+ #expect(tries == 2)
+ _ = try await bridge.handle("settings.get", [:])
+ #expect(tries == 2)
+ }
+
@Test func everyPageOperationIsRouted() {
for m in ["spaces.add", "clouds.status", "teleport.catalog", "teleport.run", "sharing.share", "volume.overview",
"agents.setupDriver", "about.set", "loginItem.set", "devices.approve", "storage.run",
diff --git a/apps/cua-spaces-web/src/bridge/README.md b/apps/cua-spaces-web/src/bridge/README.md
index 7f53e07789..8471bf6f07 100644
--- a/apps/cua-spaces-web/src/bridge/README.md
+++ b/apps/cua-spaces-web/src/bridge/README.md
@@ -33,7 +33,7 @@ import { BridgeProvider, useSpaces } from "@/bridge";
| `useSpaces()` | `Space[]` with pending creates, power changes and deletes overlaid by the core. Actions: `createSpace(req)`, `cancelCreate(pendingId)`, `dismissCreate(pendingId)`, `startSpace(id)`, `stopSpace(id)`, `deleteSpace(id)`, `openSpace(id)`. |
| `useMachines()` | `Machine[]`, this machine first, each with `spaceIds`, `connection` (`relay`, `direct`, or null before host setup), `detail`, `lastSeen` and, for this machine, `panel` (the core's `host.panel`). Also `setupGuide`: host setup in the core's words (`host.panel` choices, `host.formView`), for the Add a machine explainer. |
| `usePairingCode({ open, enabled, team? })` | "Add a machine" by link or QR code: makes a code on opening (`devices.createPairingCode`), reads `devices.pairingCodes` every 3 s until it is `used`, `revoked` or `expired`, and `revoke()` / `renew()`. `phase` is `idle`, `minting`, `ready`, `used`, `revoked`, `expired` or `error` (`error.unsupported` when the host or relay can't make codes). |
-| `useSettings()` | `{ values, telemetry, defaultLocation, page }`, where `page` is the core's Settings layout. Action: `updateSetting(key, value)` for `theme`, `menuBar`, `hotkey`, `telemetry`, `defaultLocation`, `launchAtLogin` or `updateChannel`. The last two are `null` when the host can't offer them, and the Settings page hides their rows. |
+| `useSettings()` | `{ values, telemetry, defaultLocation, page }`, where `page` is the core's Settings layout. Action: `updateSetting(key, value)` for `theme`, `menuBar`, `hotkey`, `telemetry`, `defaultLocation`, `launchAtLogin` or `updateChannel`. The last two are `null` when the host can't offer them, and the Settings page hides their rows. `globalShortcut` is the host's ⌘⇧Space (macOS) with whether the system gave it to the app; absent or `null` where the host has none. |
| `useKeyvault()` | `{ overview, groups, views, vaultState }`. `views` holds the core's `page`, `sidebar` and `vault` (the list grouped by app, then site). Actions: `unlock(passphrase?)`, `lockItem(id)`, `lockItems(ids)`, `unlockItems(ids)`, `setDisabled`, `approve`, `deny`, `revokeGrant`, `vaultAction(action)` (search, select, open), and `pane(selection)`. |
| `useSession()` | `{ fleet, onboarding, daemon, signedIn, identity, signIn }`, where `signIn` is the sign-in phase. Actions: `signIn()`, `signOut()`, `completeOnboarding(mode)`, `openExternal(url)`. |
| `useAgents()` | `{ agents, runs, unread, canList }`: persistent agents (state `running`, `paused` or `idle`, the core's row line and action label, the run the detail opens) and the runs in every running Space, in the core's order. Actions: `pauseAgent(name)`, `resumeAgent(name)`, `agentSetup()`, `configureAgents(agents?)`. |
@@ -183,8 +183,10 @@ speaks it as is:
- `machines.list` carries `hostnames` (what each relay machine's cua-spacesd
reported), so a machine and its enrolled device list once.
- `keyvault.unlock` with a passphrase fails with `native_only`.
- Onboarding stays native. Appearance and the hotkey are kept in the page,
- and an appearance change calls `window.setBackgroundColor`.
+ Onboarding stays native. Appearance is kept in the page, and an appearance
+ change calls `window.setBackgroundColor`. The host registers ⌘⇧Space
+ itself; `settings.get` carries `globalShortcut: {label, registered}`, and
+ each read tries the registration again when the system refused it.
- Touch ID and the unlock prompt stay native.
- Launch at login is the core's `launch-at-login` row. The adapter reads it
from the page and sets it with `settings.choose {row: "launch-at-login"}`,
diff --git a/apps/cua-spaces-web/src/bridge/__tests__/demo-platform.test.ts b/apps/cua-spaces-web/src/bridge/__tests__/demo-platform.test.ts
index 11f97a22a1..cd658723f8 100644
--- a/apps/cua-spaces-web/src/bridge/__tests__/demo-platform.test.ts
+++ b/apps/cua-spaces-web/src/bridge/__tests__/demo-platform.test.ts
@@ -34,6 +34,11 @@ describe("the demo host on Windows and Linux", () => {
expect((await a.call("spaces.createOptions", {})).local?.backends).toContain("lume");
});
+ it("has the global shortcut on a Mac only", async () => {
+ expect((await demo().call("settings.get", {})).globalShortcut).toEqual({ label: "\u2318\u21e7Space", registered: true });
+ expect((await demo(demoPlatformOf("win32", "x64")).call("settings.get", {})).globalShortcut).toBeNull();
+ });
+
it("names this machine after the system it runs on", async () => {
for (const [p, name] of [
[demoPlatformOf("win32", "x64"), "This PC"],
diff --git a/apps/cua-spaces-web/src/bridge/__tests__/hosts.test.ts b/apps/cua-spaces-web/src/bridge/__tests__/hosts.test.ts
index bae904e264..7cbd89ebb2 100644
--- a/apps/cua-spaces-web/src/bridge/__tests__/hosts.test.ts
+++ b/apps/cua-spaces-web/src/bridge/__tests__/hosts.test.ts
@@ -504,6 +504,14 @@ describe("webkit adapter", () => {
expect(snap.defaultLocation).toMatchObject({ source: "env", env: "CUA_ON" });
});
+ it("reads the global shortcut the host registered, and none from a host without one", async () => {
+ const taken = { label: "\u2318\u21e7Space", registered: false };
+ const withShortcut = createWebkitAdapter(webkitHost(() => ok({ ...settingsPage, globalShortcut: taken })).win);
+ expect((await withShortcut.call("settings.get", {})).globalShortcut).toEqual(taken);
+ const without = createWebkitAdapter(webkitHost(() => ok(settingsPage)).win);
+ expect((await without.call("settings.get", {})).globalShortcut).toBeNull();
+ });
+
it("reads launch at login and the update channel when the host sends them, and sets them by row", async () => {
const { win, sent } = webkitHost(() => ok(settingsWithLogin));
const a = createWebkitAdapter(win);
diff --git a/apps/cua-spaces-web/src/bridge/adapters/demo.ts b/apps/cua-spaces-web/src/bridge/adapters/demo.ts
index 25893136aa..0beef4b2c7 100644
--- a/apps/cua-spaces-web/src/bridge/adapters/demo.ts
+++ b/apps/cua-spaces-web/src/bridge/adapters/demo.ts
@@ -175,6 +175,8 @@ export function createDemoAdapter(options: DemoOptions = {}): DataAdapter & { re
defaultLocation: { value: state.settings.defaultLocation, source: "config", path: "~/.cua/config.toml" },
telemetry: demoTelemetry(state.settings.telemetry),
...(state.hostSettings ? { hostSettings: { ...state.hostSettings } } : {}),
+ // The macOS hosts register ⌘⇧Space; the Windows and Linux shells have none.
+ globalShortcut: state.platform.os === "macos" ? { label: state.settings.hotkey, registered: true } : null,
});
const overview = () => {
if (!state.keyvaultSetUp) return demoNoVaultOverview(now());
diff --git a/apps/cua-spaces-web/src/bridge/adapters/webkit.ts b/apps/cua-spaces-web/src/bridge/adapters/webkit.ts
index 74db291e32..cb1f0b3255 100644
--- a/apps/cua-spaces-web/src/bridge/adapters/webkit.ts
+++ b/apps/cua-spaces-web/src/bridge/adapters/webkit.ts
@@ -238,6 +238,7 @@ export function toSettingsSnapshot(s: WkSettings, page: Pick<SettingsValues, "th
keyvaultSiteIcons: on("keyvault-site-icons"),
keyvaultProtection: protection.length ? protection : null,
},
+ globalShortcut: s.globalShortcut ? { label: s.globalShortcut.label, registered: s.globalShortcut.registered } : null,
};
}
diff --git a/apps/cua-spaces-web/src/bridge/contracts/bridge-shapes.json b/apps/cua-spaces-web/src/bridge/contracts/bridge-shapes.json
index 87e634cf18..a9591bb349 100644
--- a/apps/cua-spaces-web/src/bridge/contracts/bridge-shapes.json
+++ b/apps/cua-spaces-web/src/bridge/contracts/bridge-shapes.json
@@ -2109,6 +2109,24 @@
}
}
}
+ },
+ "globalShortcut": {
+ "type": [
+ "object",
+ "null"
+ ],
+ "properties": {
+ "label": {
+ "type": "string"
+ },
+ "registered": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "label",
+ "registered"
+ ]
}
},
"required": [
@@ -3459,6 +3477,24 @@
"beta",
null
]
+ },
+ "globalShortcut": {
+ "type": [
+ "object",
+ "null"
+ ],
+ "properties": {
+ "label": {
+ "type": "string"
+ },
+ "registered": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "label",
+ "registered"
+ ]
}
},
"required": [
diff --git a/apps/cua-spaces-web/src/bridge/contracts/shapes.ts b/apps/cua-spaces-web/src/bridge/contracts/shapes.ts
index c28597be43..864fb3c8eb 100644
--- a/apps/cua-spaces-web/src/bridge/contracts/shapes.ts
+++ b/apps/cua-spaces-web/src/bridge/contracts/shapes.ts
@@ -61,7 +61,7 @@ import type { SentFileInfo, SpaceThumbnail, SpaceUsage, SpaceWindows } from "../
import type { RelayUsage } from "../ops/relay-usage";
import type { StartupState } from "../ops/startup";
import type { StreamTicket } from "../ops/stream";
-import type { HostSettings, HostSignIn, OpName, SessionSnapshot, SettingsSnapshot, SettingsValues } from "../protocol";
+import type { GlobalShortcut, HostSettings, HostSignIn, OpName, SessionSnapshot, SettingsSnapshot, SettingsValues } from "../protocol";
import type { WebkitMethod, WkHostState, WkMachines, WkSession, WkSettings, WkSettingsRow, WkSpace, WkSpaces } from "../webkit-protocol";
import { Defs, any, bool, dict, list, nul, nullable, num, obj, object, oneOf, opt, optNull, str, union, type Schema } from "./schema";
@@ -227,6 +227,7 @@ const SettingsShape = ref(
keyvaultProtection: optNull(list(obj<{ label: string; value: string }>()({ label: str, value: str }))),
}),
),
+ globalShortcut: optNull(obj<GlobalShortcut>()({ label: str, registered: bool })),
}),
);
@@ -899,6 +900,7 @@ const WkSettingsShape = ref(
),
}),
updateChannel: optNull(oneOf("stable", "beta")),
+ globalShortcut: optNull(object({ label: str, registered: bool })),
}),
);
diff --git a/apps/cua-spaces-web/src/bridge/index.ts b/apps/cua-spaces-web/src/bridge/index.ts
index 912881eed4..84ea552f07 100644
--- a/apps/cua-spaces-web/src/bridge/index.ts
+++ b/apps/cua-spaces-web/src/bridge/index.ts
@@ -71,6 +71,7 @@ export {
type AppearanceTheme,
type HostEvent,
type HostOperations,
+ type GlobalShortcut,
type HostSettings,
type OpName,
type SettingKey,
diff --git a/apps/cua-spaces-web/src/bridge/protocol.ts b/apps/cua-spaces-web/src/bridge/protocol.ts
index ce848d2cee..611f23f31e 100644
--- a/apps/cua-spaces-web/src/bridge/protocol.ts
+++ b/apps/cua-spaces-web/src/bridge/protocol.ts
@@ -97,6 +97,17 @@ export interface SettingsSnapshot {
* laid them out; each absent or null one is not this host's, and the page
* leaves its row out. Changed with `settings.choose`. */
hostSettings?: HostSettings;
+ /** The global shortcut that brings the app to the front, as the host
+ * registered it with the system. Absent or null: this host has none. */
+ globalShortcut?: GlobalShortcut | null;
+}
+
+/** A system-wide shortcut the host registered (macOS: ⌘⇧Space). */
+export interface GlobalShortcut {
+ /** As glyphs (`⌘⇧Space`). */
+ label: string;
+ /** False when the system refused it (another app holds the same keys). */
+ registered: boolean;
}
/** `settings::SettingsInput`'s host-only fields: the core lays out their rows. */
diff --git a/apps/cua-spaces-web/src/bridge/webkit-protocol.ts b/apps/cua-spaces-web/src/bridge/webkit-protocol.ts
index 99a5b17e89..bfe042e944 100644
--- a/apps/cua-spaces-web/src/bridge/webkit-protocol.ts
+++ b/apps/cua-spaces-web/src/bridge/webkit-protocol.ts
@@ -299,6 +299,8 @@ export interface WkSettings {
/** `AppSettings.updateChannel` (`stable` or `beta`); null while the build
* has no updater. Set with `settings.choose {row: "update-channel"}`. */
updateChannel?: string | null;
+ /** The global shortcut the host registered; absent or null: none. */
+ globalShortcut?: { label: string; registered: boolean } | null;
}
/** `keyvault.*`: the core's page views, plus the overview (camelCase records). */
diff --git a/apps/cua-spaces-web/src/lib/host-labels.test.ts b/apps/cua-spaces-web/src/lib/host-labels.test.ts
index 5b578f6250..83ce442974 100644
--- a/apps/cua-spaces-web/src/lib/host-labels.test.ts
+++ b/apps/cua-spaces-web/src/lib/host-labels.test.ts
@@ -3,7 +3,7 @@
import { describe, expect, it } from "vitest";
-import { creatingLine, hostOs, keyvaultUnlockWay, osOfPlatform, showsMacShellSettings, thisComputerLabel, thisComputerText } from "./host-labels";
+import { creatingLine, globalShortcutLine, hostOs, keyvaultUnlockWay, osOfPlatform, showsMacShellSettings, thisComputerLabel, thisComputerText } from "./host-labels";
describe("host labels", () => {
it("names the local machine after its system", () => {
@@ -26,7 +26,7 @@ describe("host labels", () => {
expect(osOfPlatform(undefined)).toBe("macos");
});
- it("keeps the menu bar and shortcut rows to the Mac", () => {
+ it("keeps the menu bar row to the Mac", () => {
expect(showsMacShellSettings("MacIntel")).toBe(true);
expect(showsMacShellSettings("Win32")).toBe(false);
expect(showsMacShellSettings("Linux x86_64")).toBe(false);
@@ -42,6 +42,13 @@ describe("host labels", () => {
expect(creatingLine("This Mac can't reach its new VM", "linux")).toBe("This Mac can't reach its new VM");
});
+ it("says what the global shortcut does, or why it does nothing", () => {
+ expect(globalShortcutLine({ label: "\u2318\u21e7Space", registered: true })).toBe("Brings Cua Spaces to the front from any app.");
+ expect(globalShortcutLine({ label: "\u2318\u21e7Space", registered: false })).toBe(
+ "Another app is using \u2318\u21e7Space, so it does nothing here. Free it in that app, then open Settings again.",
+ );
+ });
+
it("says what keeps the Keyvault's key on each system", () => {
expect(keyvaultUnlockWay("darwin")).toBe("Touch ID");
expect(keyvaultUnlockWay("win32")).toBe("Windows Hello");
diff --git a/apps/cua-spaces-web/src/lib/host-labels.ts b/apps/cua-spaces-web/src/lib/host-labels.ts
index 31b9ac0c80..4574d9ad26 100644
--- a/apps/cua-spaces-web/src/lib/host-labels.ts
+++ b/apps/cua-spaces-web/src/lib/host-labels.ts
@@ -21,9 +21,8 @@ export function thisComputerText(platform?: string): string {
}
/**
- * The menu bar switch and the global shortcut belong to the macOS app (the
- * notch, ⌘⇧Space). The Windows and Linux shells have a tray icon and no
- * global shortcut, so Settings leaves both rows out there.
+ * The menu bar switch belongs to the macOS app (the notch). The Windows and
+ * Linux shells have a tray icon instead, so Settings leaves the row out there.
*/
export function showsMacShellSettings(platform?: string): boolean {
return isMacPlatform(platform);
@@ -43,3 +42,12 @@ export function creatingLine(detail: string, platform?: string): string {
export function keyvaultUnlockWay(platform?: string): string {
return { macos: "Touch ID", windows: "Windows Hello", linux: "the system keyring" }[osOf(platform)];
}
+
+/** The line under Settings' "Global shortcut" row: what the keys do, or,
+ * when the system refused them, why they do nothing and how to fix it (the
+ * host tries again each time Settings opens). */
+export function globalShortcutLine(shortcut: { label: string; registered: boolean }): string {
+ return shortcut.registered
+ ? "Brings Cua Spaces to the front from any app."
+ : `Another app is using ${shortcut.label}, so it does nothing here. Free it in that app, then open Settings again.`;
+}
diff --git a/apps/cua-spaces-web/src/routes/settings/index.tsx b/apps/cua-spaces-web/src/routes/settings/index.tsx
index bdef71e12d..194aab04d9 100644
--- a/apps/cua-spaces-web/src/routes/settings/index.tsx
+++ b/apps/cua-spaces-web/src/routes/settings/index.tsx
@@ -17,6 +17,7 @@ import {
type SettingsPage as CorePage,
type SettingsRow as CoreRow,
type SettingsSection as CoreSection,
+ type GlobalShortcut,
} from "@/bridge";
import { writeSavedOnboarding } from "@/bridge/onboarding";
import { SettingsGroup, SettingsRow } from "@/components/settings-group";
@@ -29,7 +30,7 @@ import { Select } from "@/components/ui/select";
import { Switch } from "@/components/ui/switch";
import { lazy, Suspense } from "react";
import { toastError } from "@/components/ui/toast";
-import { showsMacShellSettings, thisComputerLabel } from "@/lib/host-labels";
+import { globalShortcutLine, showsMacShellSettings, thisComputerLabel } from "@/lib/host-labels";
import { keyvaultRows } from "@/lib/keyvault";
import { DEFAULT_KEYBINDINGS, type KeybindingCommand } from "@/lib/keybindings";
import { useTheme, type ThemePreference } from "@/lib/theme";
@@ -135,7 +136,7 @@ function CoreGeneralPage({ page }: { page: CorePage }) {
{/* The notch is the macOS app's. */}
{general ? rows(general, (r) => r.id === "notch" && !mac) : null}
<SettingsRow label="Appearance" control={<Segmented aria-label="Appearance" value={preference} options={APPEARANCE} onValueChange={setPreference} />} />
- {mac ? <SettingsRow label="Global shortcut" control={<span className="text-[13px] text-muted-foreground">{settings?.values.hotkey ?? ""}</span>} /> : null}
+ <GlobalShortcutRow shortcut={settings?.globalShortcut} />
</SettingsGroup>
<StorageSection />
@@ -162,6 +163,20 @@ function CoreGeneralPage({ page }: { page: CorePage }) {
);
}
+/** The host's global shortcut (the macOS hosts register one), and whether the system gave it. */
+function GlobalShortcutRow({ shortcut }: { shortcut: GlobalShortcut | null | undefined }) {
+ if (!shortcut) return null;
+ return (
+ <div data-global-shortcut={shortcut.registered ? "registered" : "taken"}>
+ <SettingsRow
+ label="Global shortcut"
+ description={globalShortcutLine(shortcut)}
+ control={<span className="text-[13px] text-muted-foreground">{shortcut.label}</span>}
+ />
+ </div>
+ );
+}
+
/** The relay allowance this month, where the host reads it (Electron). */
function RelayUsageRow() {
const usage = useRelayUsage();
@@ -198,23 +213,21 @@ function FallbackSettingsPage() {
<LaunchAtLoginRows />
<SettingsRow label="Appearance" control={<Segmented aria-label="Appearance" value={preference} options={APPEARANCE} onValueChange={setPreference} />} />
{showsMacShellSettings() ? (
- <>
- <SettingsRow
- label="Show in menu bar"
- description="Open Cua Spaces from the menu bar instead of the notch."
- htmlFor="menuBar"
- control={
- <Switch
- id="menuBar"
- checked={values?.menuBar ?? false}
- disabled={!values}
- onCheckedChange={(on) => void updateSetting("menuBar", on).catch(fail("Couldn't change the menu bar setting"))}
- />
- }
- />
- <SettingsRow label="Global shortcut" control={<span className="text-[13px] text-muted-foreground">{values?.hotkey ?? ""}</span>} />
- </>
+ <SettingsRow
+ label="Show in menu bar"
+ description="Open Cua Spaces from the menu bar instead of the notch."
+ htmlFor="menuBar"
+ control={
+ <Switch
+ id="menuBar"
+ checked={values?.menuBar ?? false}
+ disabled={!values}
+ onCheckedChange={(on) => void updateSetting("menuBar", on).catch(fail("Couldn't change the menu bar setting"))}
+ />
+ }
+ />
) : null}
+ <GlobalShortcutRow shortcut={settings?.globalShortcut} />
</SettingsGroup>
<StorageSection />