+
+
-
+
{integrationStatuses ? (
-
+
{(claudeIntegration || codexIntegration) && (
-
+
+
+ )}
{showClaudeConnectedIntro && (
void dismissClaudeConnectedIntro()}
@@ -1137,14 +1218,20 @@ interface OnboardingProps extends ScreenProps {
export default function Onboarding(props: OnboardingProps) {
const [step, setStep] = useState("intro");
- const appsOpeningRef = useRef(false);
+ const [isLeaving, setIsLeaving] = useState(false);
+ const leavingRef = useRef(false);
+ const authenticationHandoffStarted = useRef(false);
const { onOpenApps } = props;
- const openApps = useCallback(async () => {
- if (appsOpeningRef.current) return;
- appsOpeningRef.current = true;
+ const leave = useCallback(async () => {
+ if (leavingRef.current) return;
+ leavingRef.current = true;
+ setIsLeaving(true);
const opened = await onOpenApps();
- if (!opened) appsOpeningRef.current = false;
+ if (!opened) {
+ leavingRef.current = false;
+ setIsLeaving(false);
+ }
}, [onOpenApps]);
useEffect(() => {
@@ -1153,14 +1240,16 @@ export default function Onboarding(props: OnboardingProps) {
}, []);
useEffect(() => {
- if (!props.isAuthenticated) return;
- const nextStep = nextOnboardingStep(step, "authenticated", true);
- if (nextStep === "apps") {
- void openApps();
+ if (!props.isAuthenticated) {
+ authenticationHandoffStarted.current = false;
return;
}
- setStep(nextStep);
- }, [openApps, props.isAuthenticated, step]);
+ if (step !== "welcome" || authenticationHandoffStarted.current) return;
+ // A failed save waits for an explicit retry, even if query updates replace
+ // the callback. StrictMode must not start a second completion either.
+ authenticationHandoffStarted.current = true;
+ void leave();
+ }, [step, props.isAuthenticated, leave]);
if (step === "run") {
return (
@@ -1175,18 +1264,11 @@ export default function Onboarding(props: OnboardingProps) {
return (
void openApps()}
+ isLeaving={isLeaving}
+ onRetryCompletion={() => void leave()}
onContinue={() => {
- const nextStep = nextOnboardingStep(
- step,
- "continue",
- props.isAuthenticated,
- );
- if (nextStep === "apps") {
- void openApps();
- return;
- }
- setStep(nextStep);
+ if (props.isAuthenticated) void leave();
+ else setStep("welcome");
}}
/>
);
@@ -1195,12 +1277,12 @@ export default function Onboarding(props: OnboardingProps) {
return (
void openApps()}
+ isLeaving={isLeaving}
+ onRetryCompletion={() => void leave()}
onLocal={() => {
+ if (leavingRef.current) return;
props.onUseLocal();
- setStep((current) =>
- nextOnboardingStep(current, "local", props.isAuthenticated),
- );
+ setStep("run");
}}
/>
);
diff --git a/app/ui/app/src/components/OnboardingRoute.test.tsx b/app/ui/app/src/components/OnboardingRoute.test.tsx
new file mode 100644
index 000000000..2ced15ec4
--- /dev/null
+++ b/app/ui/app/src/components/OnboardingRoute.test.tsx
@@ -0,0 +1,182 @@
+import { StrictMode, type ComponentType } from "react";
+import { act, create, type ReactTestRenderer } from "react-test-renderer";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import * as api from "@/api";
+import { Settings } from "@/gotypes";
+import { CURRENT_ONBOARDING_VERSION } from "@/lib/onboarding";
+import { Route } from "@/routes/onboarding";
+import { WelcomeScreen } from "./Onboarding";
+
+const mocks = vi.hoisted(() => ({ navigate: vi.fn(), authenticated: true }));
+vi.mock("@tanstack/react-router", async (importOriginal) =>
+ Object.assign(
+ {},
+ await importOriginal(),
+ {
+ useNavigate: () => mocks.navigate,
+ },
+ ),
+);
+vi.mock("@/hooks/useUser", () => ({
+ useUser: () => ({
+ isAuthenticated: mocks.authenticated,
+ fetchConnectUrl: vi.fn(),
+ refetchUser: vi.fn(),
+ }),
+}));
+
+afterEach(() => {
+ vi.restoreAllMocks();
+ vi.unstubAllGlobals();
+ mocks.navigate.mockReset();
+ mocks.authenticated = true;
+});
+
+// Use the real settings mutation: query notifications replace callbacks and
+// must not automatically retry a failed handoff after authentication.
+async function renderOnboarding(authenticated: boolean) {
+ mocks.authenticated = authenticated;
+ vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+ vi.stubGlobal("navigator", { platform: "MacIntel" });
+ vi.stubGlobal("window", {
+ OLLAMA_PLATFORM: "darwin",
+ setOnboardingWindow: vi.fn(),
+ });
+ const settingsResponse = { settings: new Settings({ OnboardingVersion: 0 }) };
+ vi.spyOn(api, "getSettings").mockResolvedValue(settingsResponse);
+ const client = new QueryClient({
+ defaultOptions: {
+ queries: { retry: false, gcTime: Infinity },
+ mutations: { retry: false },
+ },
+ });
+ client.setQueryData(["settings"], settingsResponse);
+ const OnboardingRoute = Route.options.component as ComponentType;
+ const element = () => (
+
+
+
+
+ );
+ let renderer: ReactTestRenderer;
+ await act(async () => {
+ renderer = create(element());
+ });
+ const primaryAction = () =>
+ renderer.root.find(
+ (node) => node.type === "button" && "aria-busy" in node.props,
+ );
+ return {
+ get primaryAction() {
+ return primaryAction();
+ },
+ get root() {
+ return renderer.root;
+ },
+ async continue() {
+ await act(async () => {
+ const button = primaryAction();
+ button.props.onClick();
+ button.props.onClick();
+ });
+ },
+ async authenticate() {
+ mocks.authenticated = true;
+ await act(async () => {
+ renderer.update(element());
+ });
+ },
+ async unmount() {
+ await act(async () => renderer.unmount());
+ client.clear();
+ },
+ };
+}
+
+async function flushQueryNotifications() {
+ await act(async () => {
+ await new Promise((resolve) => setTimeout(resolve, 0));
+ });
+}
+
+describe("Onboarding completion", () => {
+ it.each([true, false])(
+ "saves once before opening Apps directly (already signed in: %s)",
+ async (authenticated) => {
+ let resolveSave!: (value: { settings: Settings }) => void;
+ const save = vi.spyOn(api, "updateSettings").mockImplementation(
+ () =>
+ new Promise((resolve) => {
+ resolveSave = resolve;
+ }),
+ );
+ const onboarding = await renderOnboarding(authenticated);
+ try {
+ expect(save).not.toHaveBeenCalled();
+ expect(mocks.navigate).not.toHaveBeenCalled();
+ await onboarding.continue();
+ if (!authenticated) {
+ expect(save).not.toHaveBeenCalled();
+ expect(onboarding.root.findByType(WelcomeScreen)).toBeTruthy();
+ await onboarding.authenticate();
+ }
+ await flushQueryNotifications();
+ expect(save).toHaveBeenCalledOnce();
+ expect(save).toHaveBeenCalledWith(
+ expect.objectContaining({
+ OnboardingVersion: CURRENT_ONBOARDING_VERSION,
+ }),
+ );
+ expect(mocks.navigate).not.toHaveBeenCalled();
+ expect(onboarding.primaryAction.props.disabled).toBe(true);
+ await act(async () => {
+ resolveSave({ settings: save.mock.calls[0][0] });
+ });
+ expect(mocks.navigate).toHaveBeenCalledExactlyOnceWith({
+ to: "/connect",
+ });
+ } finally {
+ await onboarding.unmount();
+ }
+ },
+ );
+
+ it.each([true, false])(
+ "keeps the current screen and waits for an explicit save retry (already signed in: %s)",
+ async (authenticated) => {
+ const save = vi
+ .spyOn(api, "updateSettings")
+ .mockRejectedValueOnce(new Error("disk full"))
+ .mockImplementation(async (settings) => ({ settings }));
+ vi.spyOn(console, "error").mockImplementation(() => {});
+ const onboarding = await renderOnboarding(authenticated);
+ try {
+ await onboarding.continue();
+ if (!authenticated) await onboarding.authenticate();
+ await flushQueryNotifications();
+ await flushQueryNotifications();
+ expect(save).toHaveBeenCalledOnce();
+ expect(mocks.navigate).not.toHaveBeenCalled();
+ expect(onboarding.primaryAction.props.disabled).toBe(false);
+ expect(onboarding.root.findByProps({ role: "alert" })).toBeTruthy();
+ await act(async () => {
+ onboarding.root
+ .find(
+ (node) =>
+ node.type === "button" && node.props.children === "Try again",
+ )
+ .props.onClick();
+ });
+ expect(save).toHaveBeenCalledTimes(2);
+ expect(save.mock.calls[1][0]).toEqual(save.mock.calls[0][0]);
+ expect(mocks.navigate).toHaveBeenCalledExactlyOnceWith({
+ to: "/connect",
+ });
+ } finally {
+ await onboarding.unmount();
+ }
+ },
+ );
+});
diff --git a/app/ui/app/src/index.css b/app/ui/app/src/index.css
index adaadb49d..f41e0bc99 100644
--- a/app/ui/app/src/index.css
+++ b/app/ui/app/src/index.css
@@ -71,9 +71,50 @@
will-change: opacity, transform;
}
-@media (prefers-reduced-motion: reduce) {
- .claude-connected-backdrop,
- .claude-connected-dialog {
- animation: none;
+.apps-copy-hint {
+ transition:
+ opacity 320ms ease-in-out,
+ transform 320ms cubic-bezier(0.22, 1, 0.36, 1);
+}
+
+.apps-copy-hint[data-closed] {
+ opacity: 0;
+ transform: translateX(16px);
+}
+
+.apps-copy-hint[data-leave] {
+ transition-duration: 400ms;
+ transition-timing-function: ease-in-out;
+}
+
+@keyframes apps-copy-card-flash {
+ 0%,
+ 100% {
+ opacity: 0;
+ }
+ 25%,
+ 50% {
+ opacity: 1;
+ }
+}
+
+.apps-copy-card-feedback {
+ animation: apps-copy-card-flash 1800ms ease-in-out both;
+}
+
+@media (prefers-reduced-motion: reduce) {
+ .claude-connected-backdrop,
+ .claude-connected-dialog,
+ .apps-copy-card-feedback {
+ animation: none;
+ }
+
+ .apps-copy-hint,
+ .apps-copy-hint[data-leave] {
+ transition: none;
+ }
+
+ .apps-copy-hint[data-closed] {
+ transform: none;
}
}
diff --git a/app/ui/app/src/lib/onboarding.ts b/app/ui/app/src/lib/onboarding.ts
index 04d69ca9a..03d5b8a65 100644
--- a/app/ui/app/src/lib/onboarding.ts
+++ b/app/ui/app/src/lib/onboarding.ts
@@ -19,24 +19,10 @@ export function onboardingConnectUrl(
export const AUTHENTICATION_TIMEOUT_MS = 5 * 60 * 1000;
-export type OnboardingStep = "intro" | "welcome" | "apps" | "run";
+export type OnboardingStep = "intro" | "welcome" | "run";
-export type OnboardingAction = "continue" | "authenticated" | "local";
export type AuthenticationTimeoutAction = "ignore" | "defer" | "fail";
-export function nextOnboardingStep(
- step: OnboardingStep,
- action: OnboardingAction,
- isAuthenticated: boolean,
-): OnboardingStep {
- if (action === "local") return "run";
- if (step === "intro" && action === "continue") {
- return isAuthenticated ? "apps" : "welcome";
- }
- if (step === "welcome" && action === "authenticated") return "apps";
- return step;
-}
-
export function authenticationTimeoutAction(
settled: boolean,
checking: boolean,
- Desktop + Recommended
{claudeRow}
@@ -1085,14 +1131,12 @@ export function ConnectAppsScreen({
+ {copyNotice && (
+ - Terminal + {isWindows ? "Apps" : "Other apps"}
-
-
- {launchIntegrations.map(launchIntegrationRow)}
-
+
+ {launchIntegrations.map(launchIntegrationCard)}
)}
@@ -1117,6 +1161,43 @@ export function ConnectAppsScreen({
+
+
+
+
+ + {copyNotice.copied + ? "Launch command copied." + : `Couldn’t copy the ${copyNotice.name} command`} +
++ {copyNotice.copied + ? "Paste it into your terminal" + : "Select and copy the command below, then paste it into your terminal."} +
+ {!copyNotice.copied && ( +
+ {copyNotice.command}
+
+ )}
+