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-web): offer Menu bar (notch or menu bar only) in the first run on a Mac (CUA-1409) (#5025)

Francesco Bonaccia429ff6c5b8b
diff --git a/apps/cua-spaces-web/src/bridge/README.md b/apps/cua-spaces-web/src/bridge/README.md
index bc2a3d6778..e98862af82 100644
--- a/apps/cua-spaces-web/src/bridge/README.md
+++ b/apps/cua-spaces-web/src/bridge/README.md
@@ -302,16 +302,17 @@ The wizard and "Connect a cloud" run the core's `wizard.*` and `cloudConnect.*`;
## First run (`onboarding.ts`)
The pages, copy and answers are the core's, the same as `OnboardingView.swift`.
-One core page needs the native app, so the web passes through it with the
-answer an unchanged native run gives: Menu bar (`presentation-picked` with
-the current `menuBar` setting). Left: Welcome with the usage-data switch,
-Sign in (optional), AI agents (detected agents, the cua skills and MCP
-server, and the cua-driver card; see "Cua Volume" below), Cua Volume (only
-with its experiment on), This machine with the permissions still to grant
-(`host.permissionRows` over `host.status`'s hints; explainers only, the
-grant stays in System Settings), and Done with a first Space
-(`wizard.pickerImages`, one per OS, created through
-`useSpaces().createSpace`).
+The pages: Welcome with the usage-data switch, Sign in (optional), AI
+agents (detected agents, the cua skills and MCP server, and the cua-driver
+card; see "Cua Volume" below), Menu bar (notch and menu bar, or menu bar
+only; the pick writes the `menuBar` setting, as Settings' notch row does),
+Cua Volume (only with its experiment on), This machine with the
+permissions still to grant (`host.permissionRows` over `host.status`'s
+hints; explainers only, the grant stays in System Settings), and Done with
+a first Space (`wizard.pickerImages`, one per OS, created through
+`useSpaces().createSpace`). Menu bar shows only where the host has the
+notch (`hasNotch`: a Mac); elsewhere the flow passes through it with the
+current `menuBar` setting and Done leaves out its "Shows in" fact.
- Progress is saved in `localStorage` (`cua-spaces:onboarding`), so the flow
resumes on the same page. "Set up later" sets `skipped`; the shell stops
diff --git a/apps/cua-spaces-web/src/bridge/__tests__/onboarding-telemetry.test.ts b/apps/cua-spaces-web/src/bridge/__tests__/onboarding-telemetry.test.ts
index 2c40e692c7..ba9db99019 100644
--- a/apps/cua-spaces-web/src/bridge/__tests__/onboarding-telemetry.test.ts
+++ b/apps/cua-spaces-web/src/bridge/__tests__/onboarding-telemetry.test.ts
@@ -1,7 +1,7 @@
// SPDX-License-Identifier: FSL-1.1-MIT
// Copyright (c) 2026 Cua AI, Inc.
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
import type { OnboardingAction, OnboardingFlowState } from "../contracts/onboarding";
import { onboardingInitial, onboardingReduce } from "../onboarding";
import { sanitizeSignals } from "../ops/telemetry";
@@ -71,7 +71,10 @@ describe("the launched signal crossing the bridge", () => {
});
describe.skipIf(!wasmBuilt)("first-run usage events from the web pages", () => {
+ afterEach(() => vi.restoreAllMocks());
+
it("never reports the Menu bar page it passes through, and counts Set up later", async () => {
+ vi.spyOn(navigator, "platform", "get").mockReturnValue("Linux x86_64");
const { act, render, waitFor } = await import("@testing-library/react");
const { createElement } = await import("react");
const { BridgeProvider, useOnboarding } = await import("../index");
diff --git a/apps/cua-spaces-web/src/bridge/__tests__/onboarding.test.tsx b/apps/cua-spaces-web/src/bridge/__tests__/onboarding.test.tsx
index fca1e68ccc..63d96fb09d 100644
--- a/apps/cua-spaces-web/src/bridge/__tests__/onboarding.test.tsx
+++ b/apps/cua-spaces-web/src/bridge/__tests__/onboarding.test.tsx
@@ -2,29 +2,59 @@
// Copyright (c) 2026 Cua AI, Inc.
import { act, cleanup, render, waitFor } from "@testing-library/react";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { createDemoAdapter } from "../adapters/demo";
import type { CoreClient } from "../core";
import { BridgeProvider, useOnboarding, useSession, useSettings, type OnboardingHook, type SessionHook, type SettingsHook } from "../index";
+import type { HostOs } from "../host-os";
import {
firstSpaceImages,
+ hasNotch,
onboardingInitial,
onboardingReduce,
onboardingTelemetry,
onboardingView,
+ passedSteps,
permissionRows,
readSavedOnboarding,
resetSavedOnboardingCache,
} from "../onboarding";
import { noCore, testCore, wasmBuilt } from "./testCore";
-const ctx = { menuBar: false };
+// Off a Mac: no notch, so the flow passes through Menu bar.
+const ctx = { menuBar: false, os: "linux" as HostOs };
+
+/** The host the hooks see (`hostOs()` reads the browser's platform). */
+const onPlatform = (platform: string) => vi.spyOn(navigator, "platform", "get").mockReturnValue(platform);
beforeEach(() => {
localStorage.clear();
resetSavedOnboardingCache();
});
-afterEach(cleanup);
+afterEach(() => {
+ cleanup();
+ vi.restoreAllMocks();
+});
+
+describe("the Menu bar page per host", () => {
+ it.each([
+ ["macos", true],
+ ["windows", false],
+ ["linux", false],
+ ] as const)("%s: notch %s", (os, notch) => {
+ expect(hasNotch(os)).toBe(notch);
+ expect(passedSteps(os)).toEqual(notch ? [] : ["presentation"]);
+ });
+
+ it("follows the host's platform (the Mac app's web view, Electron on each system)", () => {
+ onPlatform("MacIntel");
+ expect(hasNotch()).toBe(true);
+ onPlatform("Win32");
+ expect(hasNotch()).toBe(false);
+ onPlatform("Linux x86_64");
+ expect(hasNotch()).toBe(false);
+ });
+});
describe.each([
["wasm core", testCore],
@@ -33,11 +63,11 @@ describe.each([
it("walks the web pages in the core's order, past the native-only ones", async () => {
const core = await getCore();
let s = onboardingInitial(core, null);
- expect(onboardingView(core, s).dots.map((d) => d.label)).toEqual(["Welcome", "Sign in", "AI agents", "This machine", "Done"]);
+ expect(onboardingView(core, s, "linux").dots.map((d) => d.label)).toEqual(["Welcome", "Sign in", "AI agents", "This machine", "Done"]);
s = onboardingReduce(core, s, { type: "start" }, ctx);
expect(s.step).toBe("signin");
- expect(onboardingView(core, s).canSkip).toBe(true);
- expect(onboardingView(core, s).lede).toBe("Sign in for account-based access to your machines and Spaces across devices; skip to continue without it.");
+ expect(onboardingView(core, s, "linux").canSkip).toBe(true);
+ expect(onboardingView(core, s, "linux").lede).toBe("Sign in for account-based access to your machines and Spaces across devices; skip to continue without it.");
s = onboardingReduce(core, s, { type: "signin-done" }, ctx);
expect(s.step).toBe("agents");
s = onboardingReduce(core, s, { type: "agents-done", configured: ["Codex"] }, ctx);
@@ -47,9 +77,10 @@ describe.each([
s = onboardingReduce(core, s, { type: "agents-done", configured: ["Codex"] }, ctx);
s = onboardingReduce(core, s, { type: "mode-chosen", mode: "client" }, ctx);
expect(s.step).toBe("done");
- const v = onboardingView(core, s);
+ const v = onboardingView(core, s, "linux");
expect(v.title).toBe("You're all set");
expect(v.summary.map((f) => f.label)).toEqual(["Account", "AI agents", "This machine"]);
+ expect(onboardingView(core, s, "windows").summary.map((f) => f.label)).toEqual(["Account", "AI agents", "This machine"]);
// Where the app stays: the menu bar on a Mac, the tray on Windows and Linux.
expect(onboardingView(core, s, "macos").lede).toBe("Cua Spaces is in your menu bar.");
expect(onboardingView(core, s, "windows").lede).toBe("Cua Spaces is in your system tray.");
@@ -59,18 +90,57 @@ describe.each([
it("keeps the presentation setting the machine has", async () => {
const core = await getCore();
let s = onboardingReduce(core, onboardingInitial(core, null), { type: "start" }, ctx);
- s = onboardingReduce(core, s, { type: "signin-done" }, { menuBar: true });
- s = onboardingReduce(core, s, { type: "agents-done", configured: [] }, { menuBar: true });
+ s = onboardingReduce(core, s, { type: "signin-done" }, { ...ctx, menuBar: true });
+ s = onboardingReduce(core, s, { type: "agents-done", configured: [] }, { ...ctx, menuBar: true });
expect(s.menuBar).toBe(true);
});
+ it("asks where the app shows on a Mac, and Done says it", async () => {
+ const core = await getCore();
+ const mac = { menuBar: false, os: "macos" as HostOs };
+ let s = onboardingInitial(core, null);
+ expect(onboardingView(core, s, "macos").dots.map((d) => d.label)).toEqual(["Welcome", "Sign in", "AI agents", "Menu bar", "This machine", "Done"]);
+ s = onboardingReduce(core, s, { type: "start" }, mac);
+ s = onboardingReduce(core, s, { type: "signin-done" }, mac);
+ s = onboardingReduce(core, s, { type: "agents-done", configured: [] }, mac);
+ expect(s.step).toBe("presentation");
+ let v = onboardingView(core, s, "macos");
+ expect(v.title).toBe("Where should Cua Spaces show up?");
+ expect(v.lede).toBe("You can change this in Settings.");
+ expect(v.presentations?.map((c) => [c.id, c.title, c.selected])).toEqual([
+ ["onboarding-notch", "Notch and menu bar", true],
+ ["onboarding-menu-bar", "Menu bar only", false],
+ ]);
+ s = onboardingReduce(core, s, { type: "presentation-picked", menuBar: true }, mac);
+ expect(onboardingView(core, s, "macos").presentations?.find((c) => c.selected)?.title).toBe("Menu bar only");
+ s = onboardingReduce(core, s, { type: "presentation-done" }, { ...mac, menuBar: true });
+ expect(s.step).toBe("mode");
+ s = onboardingReduce(core, s, { type: "back" }, { ...mac, menuBar: true });
+ expect(s.step).toBe("presentation");
+ s = onboardingReduce(core, s, { type: "presentation-done" }, { ...mac, menuBar: true });
+ s = onboardingReduce(core, s, { type: "mode-chosen", mode: "client" }, { ...mac, menuBar: true });
+ v = onboardingView(core, s, "macos");
+ expect(v.summary.map((f) => f.label)).toEqual(["Account", "AI agents", "Shows in", "This machine"]);
+ expect(v.summary.find((f) => f.label === "Shows in")?.value).toBe("Menu bar only");
+ });
+
+ it("starts the Menu bar choice from the setting now", async () => {
+ const core = await getCore();
+ let s = onboardingInitial(core, null);
+ s = onboardingReduce(core, s, { type: "start" }, { menuBar: false, os: "macos" });
+ s = onboardingReduce(core, s, { type: "signin-done" }, { menuBar: false, os: "macos" });
+ // Changed in Settings since the flow started.
+ s = onboardingReduce(core, s, { type: "agents-done", configured: [] }, { menuBar: true, os: "macos" });
+ expect(s).toMatchObject({ step: "presentation", menuBar: true });
+ });
+
it("shows the usage switch from the setting, and locks it when the environment decides", async () => {
const core = await getCore();
let s = onboardingInitial(core, null);
s = onboardingReduce(core, s, { type: "telemetry-loaded", telemetry: { enabled: false, lockedBy: null } }, ctx);
- expect(onboardingView(core, s).usage).toMatchObject({ on: false, enabled: true });
+ expect(onboardingView(core, s, "linux").usage).toMatchObject({ on: false, enabled: true });
s = onboardingReduce(core, s, { type: "usage-data-toggled", on: true }, ctx);
- expect(onboardingView(core, s).usage?.on).toBe(true);
+ expect(onboardingView(core, s, "linux").usage?.on).toBe(true);
const locked = onboardingTelemetry({
enabled: false,
@@ -82,7 +152,7 @@ describe.each([
});
s = onboardingReduce(core, onboardingInitial(core, null), { type: "telemetry-loaded", telemetry: locked }, ctx);
s = onboardingReduce(core, s, { type: "usage-data-toggled", on: true }, ctx);
- expect(onboardingView(core, s).usage).toMatchObject({ on: false, enabled: false, help: "Set by env DO_NOT_TRACK" });
+ expect(onboardingView(core, s, "linux").usage).toMatchObject({ on: false, enabled: false, help: "Set by env DO_NOT_TRACK" });
});
it("lists only the permissions still to grant, and one image per OS", async () => {
@@ -129,6 +199,8 @@ function mount(core: CoreClient, mode?: "electron") {
}
describe.skipIf(!wasmBuilt)("useOnboarding over the demo adapter", () => {
+ beforeEach(() => onPlatform("Linux x86_64"));
+
it("saves progress, follows sign-in, writes the usage switch and finishes", async () => {
const { probe, adapter } = mount(await testCore());
await waitFor(() => expect(probe.flow.view?.usage).toBeTruthy());
@@ -174,9 +246,28 @@ describe.skipIf(!wasmBuilt)("useOnboarding over the demo adapter", () => {
});
await waitFor(() => expect(probe.flow.state?.identity).toBeNull());
});
+
+ it("on a Mac, the Menu bar pick writes the notch setting Settings shows", async () => {
+ onPlatform("MacIntel");
+ const { probe, adapter, calls } = mount(await testCore());
+ await waitFor(() => expect(probe.flow.state && probe.settings.data).toBeTruthy());
+ act(() => probe.flow.send({ type: "start" }));
+ act(() => probe.flow.send({ type: "signin-done" }));
+ act(() => probe.flow.send({ type: "agents-done", configured: [] }));
+ expect(probe.flow.view?.step).toBe("presentation");
+ act(() => probe.flow.send({ type: "presentation-picked", menuBar: true }));
+ await waitFor(() => expect(adapter.state.settings.menuBar).toBe(true));
+ expect(calls).toContainEqual(["settings.set", { key: "menuBar", value: true }]);
+ expect(probe.flow.view?.presentations?.find((c) => c.selected)?.id).toBe("onboarding-menu-bar");
+ act(() => probe.flow.send({ type: "presentation-done" }));
+ expect(probe.flow.view?.step).toBe("mode");
+ act(() => probe.flow.send({ type: "mode-chosen", mode: "client" }));
+ expect(probe.flow.view?.summary).toContainEqual({ label: "Shows in", value: "Menu bar only" });
+ });
});
describe.skipIf(!wasmBuilt)("Done's Launch at login", () => {
+ beforeEach(() => onPlatform("Linux x86_64"));
const toDone = async (probe: Probe) => {
await waitFor(() => expect(probe.flow.state).toBeTruthy());
act(() => probe.flow.send({ type: "start" }));
diff --git a/apps/cua-spaces-web/src/bridge/__tests__/volume.test.tsx b/apps/cua-spaces-web/src/bridge/__tests__/volume.test.tsx
index 6e53d9b94d..7a4f785d1a 100644
--- a/apps/cua-spaces-web/src/bridge/__tests__/volume.test.tsx
+++ b/apps/cua-spaces-web/src/bridge/__tests__/volume.test.tsx
@@ -115,6 +115,7 @@ describe.skipIf(!wasmBuilt)("the first run's Cua Volume page", () => {
act(() => probe.flow.send({ type: "start" }));
act(() => probe.flow.send({ type: "signin-done" }));
act(() => probe.flow.send({ type: "agents-done", configured: [] }));
+ act(() => probe.flow.send({ type: "presentation-done" }));
expect(probe.flow.view?.step).toBe("drive");
const card = probe.flow.view!.drive!;
expect(card.label).toBe("Add Cua Volume to Finder");
diff --git a/apps/cua-spaces-web/src/bridge/contracts/onboarding.ts b/apps/cua-spaces-web/src/bridge/contracts/onboarding.ts
index 79813465df..ee60c555e4 100644
--- a/apps/cua-spaces-web/src/bridge/contracts/onboarding.ts
+++ b/apps/cua-spaces-web/src/bridge/contracts/onboarding.ts
@@ -91,6 +91,19 @@ export interface OnboardingModeChoice {
preselected: boolean;
}
+/** `PresentationCard`: a choice on the Menu bar page. */
+export interface PresentationCard {
+ /** Menu bar only. */
+ menuBar: boolean;
+ /** "Notch and menu bar". */
+ title: string;
+ /** `onboarding-notch`, `onboarding-menu-bar`. */
+ id: string;
+ /** The miniature's spoken description. */
+ imageLabel: string;
+ selected: boolean;
+}
+
/** Welcome's "Share anonymous usage data" switch. */
export interface OnboardingUsage {
label: string;
@@ -114,6 +127,8 @@ export interface OnboardingView {
preselectedMode: OnboardingMode;
summary: OnboardingFact[];
choices: OnboardingModeChoice[];
+ /** The Menu bar page's cards (on its page only). */
+ presentations?: PresentationCard[];
notice?: string | null;
noticeLinkLabel?: string | null;
noticeLinkUrl?: string | null;
diff --git a/apps/cua-spaces-web/src/bridge/hooks.ts b/apps/cua-spaces-web/src/bridge/hooks.ts
index 56930fea7a..c5e0ae7f24 100644
--- a/apps/cua-spaces-web/src/bridge/hooks.ts
+++ b/apps/cua-spaces-web/src/bridge/hooks.ts
@@ -344,7 +344,7 @@ export function useSavedOnboarding(): SavedOnboarding {
export interface OnboardingHook {
/** The core's flow state; null until the session has loaded. */
state: OnboardingFlowState | null;
- /** The page as the core draws it (native-only pages left out). */
+ /** The page as the core draws it (the pages this host passes through left out). */
view: OnboardingView | null;
copy: OnboardingCopy;
/** Sign in's line: signed in as, or what to do in the browser. */
@@ -359,8 +359,8 @@ export interface OnboardingHook {
/** Done's "Launch at login" checkbox, where the host applies it (the
* Electron shell; the core lays it out on Done). */
launchAtLogin: OnboardingCheckbox | null;
- /** Sends an action through the core. The usage-data switch also writes
- * the machine's telemetry setting. */
+ /** Sends an action through the core. The usage-data switch and the Menu
+ * bar choice also write the machine's setting (telemetry, `menuBar`). */
send(action: OnboardingAction): void;
/** Leaves the flow for now; it resumes on the same page. */
skip(): void;
@@ -448,6 +448,11 @@ export function useOnboarding(): OnboardingHook {
if (action.type === "usage-data-toggled" && next.telemetry?.enabled === action.on && settings?.telemetry) {
void updateSetting("telemetry", action.on);
}
+ // The Menu bar choice is the "Spaces tab in the notch" setting, written
+ // at once as the SwiftUI page does.
+ if (action.type === "presentation-picked" && next.menuBar === action.menuBar && settings && settings.values.menuBar !== action.menuBar) {
+ void updateSetting("menuBar", action.menuBar);
+ }
writeSavedOnboarding({ ...readSavedOnboarding(), state: next });
};
diff --git a/apps/cua-spaces-web/src/bridge/index.ts b/apps/cua-spaces-web/src/bridge/index.ts
index 974592823c..95ce809716 100644
--- a/apps/cua-spaces-web/src/bridge/index.ts
+++ b/apps/cua-spaces-web/src/bridge/index.ts
@@ -90,7 +90,7 @@ export type * from "./contracts/settings";
export type * from "./contracts/devices";
export type * from "./contracts/notifications";
export * from "./settings-hooks";
-export { NATIVE_ONLY_STEPS, signInCodeText, type SavedOnboarding } from "./onboarding";
+export { hasNotch, passedSteps, signInCodeText, type SavedOnboarding } from "./onboarding";
export { useConnectCloud, useFirstSpaceOffers, useNewSpaceRequests, useNewSpaceWizard, type ConnectCloudHook, type FirstSpaceHook, type NewSpaceWizardHook } from "./new-space-hooks";
export { createFailedText, emptyHome, type EmptyHome, type EmptyTile, type FirstSpaceOffer } from "./new-space";
export type * from "./contracts/volume";
diff --git a/apps/cua-spaces-web/src/bridge/onboarding.ts b/apps/cua-spaces-web/src/bridge/onboarding.ts
index ff6dc3a954..2a2f276075 100644
--- a/apps/cua-spaces-web/src/bridge/onboarding.ts
+++ b/apps/cua-spaces-web/src/bridge/onboarding.ts
@@ -6,16 +6,18 @@
* (`onboarding.initial`, `.reduce`, `.view`, `.copy`), the same one the
* SwiftUI and Tauri apps draw.
*
- * One of the core's pages needs the native app, so a web host passes
- * through it with the answer a native user gets by not changing anything:
- * Menu bar (the notch), `presentation-picked` with the current setting.
- *
- * The pages left are Welcome (with the usage-data switch), Sign in, AI
- * agents (with the cua-driver card), Cua Volume (only with its experiment
+ * The pages are Welcome (with the usage-data switch), Sign in, AI agents
+ * (with the cua-driver card), Menu bar (where the app shows: the notch and
+ * the menu bar, or the menu bar only), Cua Volume (only with its experiment
* on; `volume.ts` runs its commands), This machine (with the permissions
* still to grant) and Done. The order, titles, buttons and answers are the
* core's.
*
+ * Menu bar is a Mac's: the notch is the macOS app's (the SwiftUI app, and
+ * the Electron app's notch helper). Off a Mac there is no notch, so the
+ * flow passes through that page with the answer a user gets by not
+ * changing anything, `presentation-picked` with the current setting.
+ *
* Without the core, small TypeScript stand-ins keep the demo usable. They
* are not the product's behaviour.
*/
@@ -35,16 +37,30 @@ import type {
} from "./contracts/onboarding";
import type { SpaceOs } from "./contracts/spaces";
-/** The core's pages a web host passes through (see above). */
-export const NATIVE_ONLY_STEPS: readonly OnboardingStep[] = ["presentation"];
+/** Whether the host has the notch, so the Menu bar page has a choice to
+ * offer: the macOS app's (the same rule as Settings' "Spaces tab in the
+ * notch" row). */
+export function hasNotch(os: HostOs = hostOs()): boolean {
+ return os === "macos";
+}
+
+/** The core's pages this host passes through (see above). */
+export function passedSteps(os: HostOs = hostOs()): readonly OnboardingStep[] {
+ return hasNotch(os) ? [] : ["presentation"];
+}
-/** Done's summary facts about native-only pages; the web leaves them out. */
-const NATIVE_ONLY_FACTS = new Set(["cua command", "Shows in"]);
+/** Done's summary facts about pages the web passes through: the `cua`
+ * install is the SwiftUI app's own page, Shows in follows Menu bar. */
+function passedFacts(os: HostOs): Set<string> {
+ return new Set(hasNotch(os) ? ["cua command"] : ["cua command", "Shows in"]);
+}
/** What the pass-through answers need from the host. */
export interface OnboardingContext {
/** The "Spaces tab in the notch" setting now (`menuBar`). */
menuBar: boolean;
+ /** The system the app runs on (default: this host's). */
+ os?: HostOs;
/** Sees every step the core takes, with the state before it (usage events). */
observe?: (before: OnboardingFlowState, action: OnboardingAction) => void;
}
@@ -68,8 +84,10 @@ function reduceOnce(core: CoreClient, state: OnboardingFlowState, action: Onboar
}
/**
- * The core's reducer, then past any native-only page: forward with its
- * default answer, or on back when the action was Back.
+ * The core's reducer, then past any page this host passes through: forward
+ * with its default answer, or on back when the action was Back. Landing on
+ * Menu bar, the choice starts from the setting now (it may have changed in
+ * Settings since the flow started), as the SwiftUI page does on appear.
*/
export function onboardingReduce(
core: CoreClient,
@@ -77,8 +95,9 @@ export function onboardingReduce(
action: OnboardingAction,
ctx: OnboardingContext,
): OnboardingFlowState {
+ const passed = passedSteps(ctx.os);
let s = reduceOnce(core, state, action, ctx);
- for (let guard = 0; guard < NATIVE_ONLY_STEPS.length + 1 && NATIVE_ONLY_STEPS.includes(s.step); guard++) {
+ for (let guard = 0; guard < passed.length + 1 && passed.includes(s.step); guard++) {
const before = s.step;
if (action.type === "back") {
s = reduceOnce(core, s, { type: "back" }, ctx);
@@ -90,17 +109,23 @@ export function onboardingReduce(
}
if (s.step === before) break;
}
+ if (s.step === "presentation" && state.step !== "presentation" && s.menuBar !== ctx.menuBar) {
+ s = reduceOnce(core, s, { type: "presentation-picked", menuBar: ctx.menuBar }, ctx);
+ }
return s;
}
-/** The page as drawn, without the native-only pages' dots and facts, in
- * the words of the system the app runs on (the tray off a Mac). */
+/** The page as drawn, without the dots and facts of the pages this host
+ * passes through, in the words of the system the app runs on (the tray off
+ * a Mac). */
export function onboardingView(core: CoreClient, state: OnboardingFlowState, os: HostOs = hostOs()): OnboardingView {
const v = core.tryCall<OnboardingView>("onboarding.view", { state, hostOs: os }) ?? fallbackView(state, os);
+ const passed = passedSteps(os);
+ const facts = passedFacts(os);
return {
...v,
- dots: v.dots.filter((d) => !NATIVE_ONLY_STEPS.includes(d.step)),
- summary: v.summary.filter((f) => !NATIVE_ONLY_FACTS.has(f.label)),
+ dots: v.dots.filter((d) => !passed.includes(d.step)),
+ summary: v.summary.filter((f) => !facts.has(f.label)),
};
}
@@ -209,6 +234,7 @@ function fallbackView(s: OnboardingFlowState, os: HostOs): OnboardingView {
const pages: Partial<Record<OnboardingStep, [string, string, string]>> = {
welcome: ["Welcome to Cua Spaces", "Computers for you and your agents.", "Get started"],
signin: ["Sign in", "Sign in for account-based access to your machines and Spaces across devices; skip to continue without it.", "Continue"],
+ presentation: ["Where should Cua Spaces show up?", "You can change this in Settings.", "Continue"],
mode: ["How will you use this machine?", "You can change this later.", "Continue"],
done: ["You're all set", os === "macos" ? "Cua Spaces is in your menu bar." : "Cua Spaces is in your system tray.", "Start using Cua Spaces"],
};
@@ -230,6 +256,7 @@ function fallbackView(s: OnboardingFlowState, os: HostOs): OnboardingView {
? [
{ label: "Account", value: s.identity ?? "not signed in" },
{ label: "AI agents", value: Array.isArray(s.agents) && s.agents.length ? s.agents.join(", ") : "none" },
+ { label: "Shows in", value: s.menuBar ? "Menu bar only" : "Notch and menu bar" },
{ label: "This machine", value: s.mode === "host" ? "Set up for unattended access" : "Access other machines" },
]
: [],
@@ -240,6 +267,13 @@ function fallbackView(s: OnboardingFlowState, os: HostOs): OnboardingView {
{ mode: "host", label: "Set up this machine for unattended access", preselected: pre === "host" },
]
: [],
+ presentations:
+ s.step === "presentation"
+ ? [
+ { menuBar: false, title: "Notch and menu bar", id: "onboarding-notch", imageLabel: "The Spaces tiles open from the notch, and the menu bar menu", selected: !s.menuBar },
+ { menuBar: true, title: "Menu bar only", id: "onboarding-menu-bar", imageLabel: "The menu bar menu alone", selected: s.menuBar },
+ ]
+ : [],
notice: s.step === "welcome" ? "Cua collects anonymous usage data. Change it here or in Settings, Privacy." : null,
noticeLinkLabel: s.step === "welcome" ? "What is collected" : null,
noticeLinkUrl: s.step === "welcome" ? "https://cua.ai/docs/cua-sdk/concepts/telemetry" : null,
diff --git a/apps/cua-spaces-web/src/bridge/store.ts b/apps/cua-spaces-web/src/bridge/store.ts
index a0dea2f82d..872addb192 100644
--- a/apps/cua-spaces-web/src/bridge/store.ts
+++ b/apps/cua-spaces-web/src/bridge/store.ts
@@ -13,6 +13,7 @@ import { isUnsupported, type DataAdapter } from "./adapter";
import type { AgentRunStatus, AgentSetupRow, PersistentAgent, SpaceAgentRun } from "./contracts/agents";
import type { CoreClient } from "./core";
import { withCreateContext } from "./create-context";
+import { passedSteps } from "./onboarding";
import type { MachineRow, OnboardingMode, SettingsPage, SignInPhase, SignInStart, SpaceCreateConfig, TelemetryView } from "./contracts/host";
import type { OnboardingAction, OnboardingFlowState } from "./contracts/onboarding";
import type { KeyvaultOverview, KvGrant, KvListView, KvSelection, VaultAction, VaultState } from "./contracts/keyvault";
@@ -88,10 +89,6 @@ export interface SessionData extends SessionSnapshot {
}
-/** The core's telemetry names of the pages a web host passes through
- * (`NATIVE_ONLY_STEPS`): never on screen here, so never reported. */
-const UNSEEN_PAGES = new Set(["presentation"]);
-
/** What a persistent agent is doing: paused, a turn running, or waiting. */
export type AgentState = "running" | "paused" | "idle";
@@ -306,9 +303,10 @@ export class BridgeStore {
/** The events a first-run step means, from the state before it. */
trackOnboarding(before: OnboardingFlowState, action: OnboardingAction): void {
- // The pages the web passes through unseen (Menu bar) are not reported.
+ // The pages this host passes through unseen (Menu bar off a Mac) are not reported.
+ const unseen: readonly string[] = passedSteps();
const seen = telemetryOnboarding(this.core, before, action).filter(
- (s) => s.type !== "onboarding-page" || !UNSEEN_PAGES.has(s.page),
+ (s) => s.type !== "onboarding-page" || !unseen.includes(s.page),
);
void this.telemetry.track(seen);
}
diff --git a/apps/cua-spaces-web/src/components/__tests__/onboarding-mode.test.tsx b/apps/cua-spaces-web/src/components/__tests__/onboarding-mode.test.tsx
index 7e2094d543..ad156c4a6f 100644
--- a/apps/cua-spaces-web/src/components/__tests__/onboarding-mode.test.tsx
+++ b/apps/cua-spaces-web/src/components/__tests__/onboarding-mode.test.tsx
@@ -39,6 +39,7 @@ describe.skipIf(!wasmBuilt)("This machine in the first run", () => {
act(() => probe.flow.send({ type: "start" }));
act(() => probe.flow.send({ type: "signin-done" }));
act(() => probe.flow.send({ type: "agents-done", configured: [] }));
+ act(() => probe.flow.send({ type: "presentation-done" }));
const hostChoice = await screen.findByTestId("onboarding-host");
expect(hostChoice).not.toHaveProperty("disabled", true);
expect(screen.queryByText(/Available once this machine is set up/)).toBeNull();
@@ -67,6 +68,7 @@ describe.skipIf(!wasmBuilt)("This machine in the first run", () => {
act(() => probe.flow.send({ type: "start" }));
act(() => probe.flow.send({ type: "signin-done" }));
act(() => probe.flow.send({ type: "agents-done", configured: [] }));
+ act(() => probe.flow.send({ type: "presentation-done" }));
fireEvent.click(await screen.findByTestId("onboarding-client"));
expect(readSavedOnboarding().state).toMatchObject({ step: "done", mode: "client" });
});
diff --git a/apps/cua-spaces-web/src/components/__tests__/onboarding-presentation.test.tsx b/apps/cua-spaces-web/src/components/__tests__/onboarding-presentation.test.tsx
new file mode 100644
index 0000000000..2d24889bd5
--- /dev/null
+++ b/apps/cua-spaces-web/src/components/__tests__/onboarding-presentation.test.tsx
@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: FSL-1.1-MIT
+// Copyright (c) 2026 Cua AI, Inc.
+
+import { act, cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { BridgeProvider, useOnboarding, type OnboardingHook } from "@/bridge";
+import { createDemoAdapter } from "@/bridge/adapters/demo";
+import { resetSavedOnboardingCache } from "@/bridge/onboarding";
+import { testCore, wasmBuilt } from "@/bridge/__tests__/testCore";
+import { PresentationCards } from "@/components/onboarding-presentation";
+
+beforeEach(() => {
+ localStorage.clear();
+ resetSavedOnboardingCache();
+});
+afterEach(() => {
+ cleanup();
+ vi.restoreAllMocks();
+});
+
+const probe = {} as { flow: OnboardingHook };
+
+function Page() {
+ const flow = useOnboarding();
+ probe.flow = flow;
+ if (flow.view?.step !== "presentation") return null;
+ return <PresentationCards flow={flow} view={flow.view} />;
+}
+
+async function toMenuBarPage() {
+ const adapter = createDemoAdapter({ latencyMs: 1, stepMs: 1, signedIn: false, onboarded: false });
+ render(
+ <BridgeProvider adapter={adapter} core={await testCore()} storeOptions={{ tickMs: 5 }}>
+ <Page />
+ </BridgeProvider>,
+ );
+ await waitFor(() => expect(probe.flow.state).toBeTruthy());
+ act(() => probe.flow.send({ type: "start" }));
+ act(() => probe.flow.send({ type: "signin-done" }));
+ act(() => probe.flow.send({ type: "agents-done", configured: [] }));
+ return adapter;
+}
+
+describe.skipIf(!wasmBuilt)("Menu bar in the first run", () => {
+ it("offers the notch on a Mac and writes the pick to the setting", async () => {
+ vi.spyOn(navigator, "platform", "get").mockReturnValue("MacIntel");
+ const adapter = await toMenuBarPage();
+ const notch = await screen.findByTestId("onboarding-notch");
+ const menuBar = screen.getByTestId("onboarding-menu-bar");
+ expect(notch.textContent).toBe("Notch and menu bar");
+ expect(notch.getAttribute("aria-checked")).toBe("true");
+ expect(screen.getByRole("img", { name: "The menu bar menu alone" })).toBeTruthy();
+
+ fireEvent.click(menuBar);
+ await waitFor(() => expect(adapter.state.settings.menuBar).toBe(true));
+ expect(screen.getByTestId("onboarding-menu-bar").getAttribute("aria-checked")).toBe("true");
+ });
+
+ it("passes through off a Mac", async () => {
+ vi.spyOn(navigator, "platform", "get").mockReturnValue("Win32");
+ await toMenuBarPage();
+ expect(probe.flow.view?.step).toBe("mode");
+ expect(screen.queryByTestId("onboarding-notch")).toBeNull();
+ });
+});
diff --git a/apps/cua-spaces-web/src/components/onboarding-presentation.tsx b/apps/cua-spaces-web/src/components/onboarding-presentation.tsx
new file mode 100644
index 0000000000..af74923f71
--- /dev/null
+++ b/apps/cua-spaces-web/src/components/onboarding-presentation.tsx
@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: FSL-1.1-MIT
+// Copyright (c) 2026 Cua AI, Inc.
+
+import type { OnboardingHook, OnboardingView } from "@/bridge";
+import { cn } from "@/lib/utils";
+
+/** The Menu bar page's choices, side by side, as the SwiftUI page draws them:
+ * a miniature of the top of the screen, and the card's title. */
+export function PresentationCards({ flow, view }: { flow: OnboardingHook; view: OnboardingView }) {
+ return (
+ <div role="radiogroup" aria-label={view.title} className="grid grid-cols-2 gap-3">
+ {(view.presentations ?? []).map((card) => (
+ <button
+ key={card.id}
+ type="button"
+ role="radio"
+ aria-checked={card.selected}
+ data-testid={card.id}
+ onClick={() => flow.send({ type: "presentation-picked", menuBar: card.menuBar })}
+ className={cn(
+ "flex flex-col items-center gap-2 rounded-xl border bg-card p-2 shadow-xs outline-none transition-[border-color,box-shadow]",
+ "hover:border-foreground/20 focus-visible:border-brand focus-visible:ring-3 focus-visible:ring-brand/25",
+ card.selected && "border-foreground/40",
+ )}
+ >
+ <ScreenTop notch={!card.menuBar} label={card.imageLabel} />
+ <span className="text-[12.5px] font-medium">{card.title}</span>
+ </button>
+ ))}
+ </div>
+ );
+}
+
+/** The top of a Mac's screen: the menu bar with the app's icon, and the
+ * notch where the Spaces tiles open (when it shows there). */
+function ScreenTop({ notch, label }: { notch: boolean; label: string }) {
+ return (
+ <div role="img" aria-label={label} className="relative h-20 w-full overflow-hidden rounded-md bg-gradient-to-b from-sky-200 to-indigo-300 dark:from-slate-700 dark:to-indigo-950">
+ <div className="absolute inset-x-0 top-0 flex h-3 items-center justify-end gap-1 bg-white/50 px-1.5 dark:bg-black/40">
+ <span className="size-1.5 rounded-full bg-foreground/70" />
+ <span className="h-1 w-3 rounded-full bg-foreground/30" />
+ </div>
+ {notch ? (
+ <div className="absolute top-0 left-1/2 h-3 w-12 -translate-x-1/2 rounded-b-md bg-black">
+ <div className="absolute top-3 left-1/2 flex -translate-x-1/2 gap-1 rounded-b-md bg-black px-1.5 pt-0.5 pb-1.5">
+ <span className="h-3 w-4 rounded-[2px] bg-white/70" />
+ <span className="h-3 w-4 rounded-[2px] bg-white/40" />
+ <span className="h-3 w-4 rounded-[2px] bg-white/40" />
+ </div>
+ </div>
+ ) : null}
+ </div>
+ );
+}
diff --git a/apps/cua-spaces-web/src/routes/onboarding/index.tsx b/apps/cua-spaces-web/src/routes/onboarding/index.tsx
index 3a1b72fe98..3a6bbd42e6 100644
--- a/apps/cua-spaces-web/src/routes/onboarding/index.tsx
+++ b/apps/cua-spaces-web/src/routes/onboarding/index.tsx
@@ -9,6 +9,7 @@ import { CuaLogo } from "@/components/cua-logo";
import { useAgentsStep, type AgentsStep } from "@/components/volume/use-agents-step";
import { OsIcon } from "@/components/os-icon";
import { ModeCard } from "@/components/onboarding-mode";
+import { PresentationCards } from "@/components/onboarding-presentation";
import { pressPrimaryOnReturn } from "@/components/onboarding-keys";
import { SetUpLater } from "@/components/onboarding-skip";
import { SignInLink } from "@/components/sign-in-link";
@@ -161,6 +162,7 @@ function Columns({ flow, view, agents }: { flow: OnboardingHook; view: Onboardin
</Suspense>
</Card>
) : null}
+ {view.step === "presentation" ? <PresentationCards flow={flow} view={view} /> : null}
{view.step === "drive" && view.drive ? (
<Card>
<Suspense fallback={null}>
@@ -467,6 +469,12 @@ function Trailing({ flow, view, agents, onFinish }: { flow: OnboardingHook; view
)}
</>
);
+ case "presentation":
+ return (
+ <Button size="lg" data-onboarding-primary="" onClick={() => flow.send({ type: "presentation-done" })}>
+ {view.primaryLabel}
+ </Button>
+ );
case "drive":
return (
<Button
@@ -489,7 +497,7 @@ function Trailing({ flow, view, agents, onFinish }: { flow: OnboardingHook; view
</Button>
);
default:
- // Welcome has its own button; the native-only pages never show here.
+ // Welcome has its own button.
return null;
}
}