Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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) => vologinItem: 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.tsnew file mode 100644index 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.tsindex 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: Settingsit("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.tsindex 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.swiftnew file mode 100644index 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.swiftindex 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.swiftindex 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.swiftindex 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.mdindex 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-spacesdreported), 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 itfrom 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.tsindex 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.tsindex 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.tsindex 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 & { redefaultLocation: { 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.tsindex 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, "thkeyvaultSiteIcons: 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsxindex 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 />